RotatingFile structv0.1.0

A log file that starts afresh before a write would take it past a size.

pub struct RotatingFile {
    // private fields
}

The current file keeps the path it was opened at. Moving it aside renames it to path.1, after renaming an older path.1 to path.2 and so on up to path.<keep>, whose previous contents are replaced; with keep zero the current file is emptied instead. The file is moved aside only before a write, never during one, and a Logger hands each record over in one write, so a record never spans two files: one larger than the limit goes whole into a file of its own. Move-only: the file closes exactly once, through Close or the destructor.

Associated functions

`Open`

pub func Open(
    allocator: Allocator,
    path: Path,
    limit: uint64,
    keep: uint
) -> RotatingFile ! IoError

Opens path for appending, creating it if missing, to be moved aside before it grows past limit bytes.

Name	Type	Description
`allocator`	`Allocator`	where the storage comes from
`path`	`Path`	the current log file's path
`limit`	`uint64`	the size in bytes a write may not take the current file past; at least one
`keep`	`uint`	how many older files to keep, as `path.1` to `path.<keep>`

Returns: the open file, or why it could not be opened; InvalidInput for a zero limit or an overlong path

Source

Methods

`Size`

pub func Size(self: &RotatingFile) -> uint64

How many bytes the current file holds.

Returns: its size, counting what this value wrote

Source

`Rotate`

pub func Rotate(self: &var RotatingFile) -> ! IoError

Moves the current file aside now and starts an empty one, whatever its size. The file is closed first, because Windows renames no open file. A failure leaves the current file closed, and every later write fails with InvalidHandle until a rotation succeeds.

Returns: success when an empty current file is open

Source

`Close`

pub func Close(self: &var RotatingFile) -> ! IoError

Closes the current file, reporting what closing it said.

Returns: success when the file is closed

Source

`Stream`

pub func Stream(self: *var RotatingFile) -> RotatingStream

A stored borrow of this file for a Logger, which keeps its destination. The file must outlive the stream and must not be moved while one exists; nothing tracks either.

Returns: a stream writing through this file

Source

Implements Writer

RotatingFile conforms to Writer.

`Write`

pub func Write(
    self: &var RotatingFile,
    bytes: char8[..]
) -> uint ! IoError

Writes bytes, moving the current file aside first when they would take it past the limit. An empty current file is never moved aside, so a write larger than the limit lands whole in a fresh file.

Name	Type	Description
`bytes`	`char8[..]`	the bytes to write

Returns: how many bytes were taken

Source

`Flush`

pub func Flush(self: &var RotatingFile) -> ! IoError

Flushes the current file, which holds nothing back.

Returns: success when everything written reached the system

Source

Records

The formats a log record is written in: text or JSON lines.

RotatingStream

A stored borrow of a RotatingFile that speaks Writer, for a Logger to keep.

Edit this page on GitHub