BitLogger/docs/api/file-rotation-i64.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
file-rotation-i64	api	sink	20260705	Create a native-focused large-file rotation policy using an Int64 byte threshold.	file rotation i64 native

File-rotation-i64

Create a size-based file rotation policy with an Int64 byte threshold. This helper is the opt-in native-focused path for large-file rotation scenarios that exceed the default Int-based contract.

Interface

pub fn file_rotation_i64(max_bytes : Int64, max_backups~ : Int = 1) -> FileRotation {}

input

• max_bytes : Int64 - Maximum active file size threshold before rotation on the native-focused wide path.
• max_backups : Int - Number of retained backup files.

output

• FileRotation - Rotation policy value that preserves a native wide threshold while staying compatible with the existing file sink API surface.

Explanation

• max_bytes <= 0L is normalized to 1L.
• max_backups <= 0 is normalized to 1.
• Rotation is size-based only.
• This helper keeps the existing FileRotation type but stores an additional native wide threshold internally for runtime rotation checks.
• The helper is intended for native file backends and advanced large-file scenarios.
• JSON config export helpers preserve the exact threshold through max_bytes_i64 while still exposing a compatibility max_bytes view.

How to Use

When Need Native Large-file Rotation Thresholds

let sink = file_sink(
  "app.log",
  rotation=Some(file_rotation_i64(5368709120L, max_backups=4)),
)

In this example, the active rotation threshold is expressed with Int64 rather than the default Int path.

When Need A Wide Policy Value First

let rotation = file_rotation_i64(3221225472L, max_backups=2)
let sink = file_sink("app.log", rotation=Some(rotation))

In this example, the wide threshold policy is assembled separately and then reused.

Error Case

• If max_bytes is non-positive, it is clamped to 1L.
• This API does not make non-native targets gain real file support; callers should still use native_files_supported() when portability matters.

Notes

1. This API is additive and does not replace the default file_rotation(...) contract.
2. Prefer the default Int path unless a native large-file threshold is actually required.
3. String-based JSON roundtrip uses max_bytes_i64 for the exact threshold and keeps max_bytes as the compatibility field.
4. This helper is designed for advanced use and target-aware code.