Struct chronicle::queue::RollCycle

#[repr(transparent)]pub struct RollCycle {
    pub repr: u8,
}

Expand description

A Chronicle Queue is a logical view of a directory on the file system. The queue data is split across multiple files, each of which contains data belonging to a single cycle. The length of the cycle is determined by the rollcycle parameter passed to the queue builder.

Example options are:

RollCycle::Daily: events stored in the queue will be grouped into 24-hour periods
RollCycle::Hourly: a new queue file will be created every hour

As new files are created (the queue is rolled) to accommodate events being written to the queue, a persisted data-structure (the .cq4t file) is updated with the lowest and highest cycle numbers present in the directory. Maintaining this table allows an ExcerptTailer to busy-spin waiting for new data to be appended to the queue, without the need to make costly calls to the file system to check for the existence of new queue files.

The interval for rolling is configured using the queue’s rollcycle attribute, for example:

let queue = queue::SingleChronicleQueueBuilder::new("example")
                .rollcycle(RollCycle::Daily)
                .build()
                .unwrap();

The roll cycle is fixed once the first data is appended to the queue. If an attempt is made to open an existing queue with a different rollcycle passed to the SingleChronicleQueueBuilder then the queue’s existing roll cycle will take priority and be used instead. (A corresponding warning message will also be logged).

Note: file rolling is a relatively expensive operation and it is recommended to schedule rolling during quiet periods wherever possible.

In addition to controlling the frequency of file rolling, the RollCycle also imposes some limits on the maximum number of messages per cycle (ie per .cq4 file). These limits are rarely intrusive, but some use cases will dictate the choice of RollCycle.

The default RollCycle is FastDaily and this is appropriate for most use cases. It is recommended to start with the FastDaily roll cycle then change only when a specific need arises.

The complete list of roll cycles, together with relevant limits are listed in the below table.

Note: Roll cycles with Test in the name are very short duration cycles which can be used to check behaviour on file rolling (eg if bespoke callbacks have been registered). These are not suitable for use outside of testing.

Roll Cycle Name	Max number of msgs per cycle (dec / hex)	Averaged max number of msgs per second
`FiveMinutely`	`1,073,741,824 / 0x40000000`	`3,579,139`
`TenMinutely`	`1,073,741,824 / 0x40000000`	`1,789,569`
`TwentyMinutely`	`1,073,741,824 / 0x40000000`	`1,491,308`
`HalfHourly`	`1,073,741,824 / 0x40000000`	`596,523`
`FastHourly`	`4,294,967,295 / 0xffffffff`	`1,193,046`
`TwoHourly`	`4,294,967,295 / 0xffffffff`	`596,523`
`FourHourly`	`4,294,967,295 / 0xffffffff`	`298,261`
`SixHourly`	`4,294,967,295 / 0xffffffff`	`198,841`
`FastDaily`	`4,294,967,295 / 0xffffffff`	`49,710`
`Minutely`	`67,108,864 / 0x4000000`	`1,118,481`
`Hourly`	`268,435,456 / 0x10000000`	`74,565`
`Daily`	`4,294,967,295 / 0xffffffff`	`49,710`
`LargeHourly`	`4,294,967,295 / 0xffffffff`	`49,710`
`LargeDaily`	`137,438,953,471 / 0x1fffffffff`	`1,590,728`
`XLargeDaily`	`4,398,046,511,103 / 0x3ffffffffff`	`50,903,316`
`HugeDaily`	`281,474,976,710,655 / 0xffffffffffff`	`3,257,812,230`
`SmallDaily`	`536,870,912 / 0x20000000`	`6,213`
`LargeHourlySparse`	`17,179,869,183 / 0x3ffffffff`	`4,772,185`
`LargeHourlyXSparse`	`4,398,046,511,103 / 0x3ffffffffff`	`1,221,679,586`
`HugeDailyXSparse`	`281,474,976,710,655 / 0xffffffffffff`	`78,187,493,530`
`TestSecondly`	`4,294,967,295 / 0xffffffff`	`4,294,967,295`
`Test4Secondly`	`4,096 / 0x1000`	`4,096`
`TestHourly`	`1,024 / 0x400`	`0`
`TestDaily`	`64 / 0x40`	`0`
`Test2Daily`	`512 / 0x200`	`0`
`Test4Daily`	`4,096 / 0x1000`	`0`
`Test8Daily`	`131,072 / 0x20000`	`1`