Struct chronicle::queue::SingleChronicleQueue

#[repr(C)]
pub struct SingleChronicleQueue { /* private fields */ }
Expand description

A SingleChronicleQueue instance provides a handle to a Chronicle Queue, which in turn represents a single, ordered, logical queue of persisted data. A single logical queue may be backed by multiple memory-mapped files depending on the associated RollCycle (eg use a new file for each day). The SingleChronicleQueue handle abstracts the physical layout of the queue, segmentation, rolling etc.

A SingleChronicleQueue handle can be safely copied and shared across threads.

Once a SingleChronicleQueue handle has been obtained (typically from a SingleChronicleQueueBuilder) most interaction is proxied through an ExcerptAppender or an ExcerptTailer to write or read content respectively.

Example

use chronicle::*;

// acquire a handle to a SingleChronicleQueue
// (the queue will be created if it doesn't already exist)
let queue = queue::SingleChronicleQueueBuilder::new("example").build().unwrap();

// all writes to the queue take place through an ExcerptAppender handle
let appender = queue.acquire_appender().unwrap();
appender.write_string("data");

// all reads from the queue take place through an ExcerptTailer handle
let tailer = queue.create_tailer().unwrap();
let str = tailer.read_string();

Implementations§

Get an ExcerptAppender handle for adding content to the queue.

An ExcerptAppender has mutable access to a queue and cannot be shared. Any number of ExcerptAppenders can be opened on a queue.

Note: Each appender holds a write lock for the duration of a write action, so multiple concurrent writes will contend for access to the queue. For this reason it is generally recommended to limit the number of concurrent writers where predictable latencies are important. For the avoidance of doubt, multiple appenders is not in itself a concern and is frequently a valid design pattern, however care should be taken to avoid contention arising when multiple writers attempt to append to the queue at the same time.

See ExcerptAppender for full details

Get an ExcerptTailer handle for reading content from the queue.

ExcerptTailers can be freely copied and shared, and any number of tailers can be opened on a queue. ExcerptTailers do not contend with appenders, and there is no performance impact from having a large number of tailers.

See ExcerptTailer for full details.

Get a named ExcerptTailer handle for reading content from the queue.

ExcerptTailers can be freely copied and shared, and any number of tailers can be opened on a queue. ExcerptTailers do not contend with appenders, and there is no performance impact from having a large number of tailers.

A named ExcerptTailer maintains internal state such that when a tailer with the same name is re-acquired (eg after restarting a process) it will resume from the last position it read.

See ExcerptTailer for full details.

Dump the contents of a queue (.cq4 files) in canonical hexdump format. Can be useful when analysing queue data and/or for debugging

Returns

A string containing the hexdump

Example
let q = queue::SingleChronicleQueueBuilder::new("example").build().unwrap();

let appender = q.acquire_appender().unwrap();
{
    let context = appender.scoped_writing_document();
    let wire = context.wire();
    let value_out = wire.value_out();
    value_out.string("hello world");
    value_out.boolean(true);
    value_out.int8(-65);
    value_out.uint8(65);
    value_out.int16(-1234);
    value_out.uint16(1234);
    value_out.int32(-5678);
    value_out.uint32(5678);
    value_out.int64(6789);
    value_out.float32(3.14);
    value_out.float64(2.718);

    let v = vec![1,2,3,4];
    value_out.bytes(&v);

    let simple = Simple { val1: 42, val2: 3.14 };
    value_out.object(&simple);

    let bytes = context.bytes();
    bytes.write_i32(1234);
}

let v2 = vec![5,6,7,8];
appender.write_slice(&v2);

println!("{}", q.dump());

// prints the following
00000000 b0 00 00 40 b9 06 68 65  61 64 65 72 b6 07 53 54 ···@··he ader··ST
00000010 53 74 6f 72 65 82 9a 00  00 00 c8 77 69 72 65 54 Store··· ···wireT
00000020 79 70 65 b6 08 57 69 72  65 54 79 70 65 ec 42 49 ype··Wir eType·BI
00000030 4e 41 52 59 5f 4c 49 47  48 54 c8 6d 65 74 61 64 NARY_LIG HT·metad
00000040 61 74 61 b6 07 53 43 51  4d 65 74 61 82 60 00 00 ata··SCQ Meta·`··
00000050 00 c4 72 6f 6c 6c b6 08  53 43 51 53 52 6f 6c 6c ··roll·· SCQSRoll
00000060 82 27 00 00 00 c6 6c 65  6e 67 74 68 a6 00 5c 26 ·'····le ngth··\&
00000070 05 c6 66 6f 72 6d 61 74  eb 79 79 79 79 4d 4d 64 ··format ·yyyyMMd
00000080 64 27 46 27 c5 65 70 6f  63 68 a1 00 d7 64 65 6c d'F'·epo ch···del
00000090 74 61 43 68 65 63 6b 70  6f 69 6e 74 49 6e 74 65 taCheckp ointInte
000000a0 72 76 61 6c a1 40 c8 73  6f 75 72 63 65 49 64 a1 rval·@·s ourceId·
000000b0 00 8f 8f 8f 20 00 00 00  b9 14 6c 69 73 74 69 6e ···· ··· ··listin
000000c0 67 2e 68 69 67 68 65 73  74 43 79 63 6c 65 8f a7 g.highes tCycle··
000000d0 f0 4b 00 00 00 00 00 00  24 00 00 00 b9 13 6c 69 ·K······ $·····li
000000e0 73 74 69 6e 67 2e 6c 6f  77 65 73 74 43 79 63 6c sting.lo westCycl
000000f0 65 8e 01 00 00 00 00 a7  f0 4b 00 00 00 00 00 00 e······· ·K······
00000100 1c 00 00 00 b9 10 6c 69  73 74 69 6e 67 2e 6d 6f ······li sting.mo
00000110 64 43 6f 75 6e 74 8f a7  03 00 00 00 00 00 00 00 dCount·· ········
00000120 24 00 00 00 b9 14 63 68  72 6f 6e 69 63 6c 65 2e $·····ch ronicle.
00000130 71 75 65 75 65 2e 6c 6f  63 6b 8e 00 00 00 00 a7 queue.lo ck······
00000140 00 00 00 00 00 00 00 80  24 00 00 00 b9 14 63 68 ········ $·····ch
00000150 72 6f 6e 69 63 6c 65 2e  77 72 69 74 65 2e 6c 6f ronicle. write.lo
00000160 63 6b 8e 00 00 00 00 a7  00 00 00 00 00 00 00 80 ck······ ········
00000170 24 00 00 00 b9 15 63 68  72 6f 6e 69 63 6c 65 2e $·····ch ronicle.
00000180 61 70 70 65 6e 64 2e 6c  6f 63 6b 8f 8f 8f 8f a7 append.l ock·····
00000190 00 00 00 00 00 00 00 80  2c 00 00 00 b9 1d 63 68 ········ ,·····ch
000001a0 72 6f 6e 69 63 6c 65 2e  6c 61 73 74 49 6e 64 65 ronicle. lastInde
000001b0 78 52 65 70 6c 69 63 61  74 65 64 8f 8f 8f 8f a7 xReplica ted·····
000001c0 ff ff ff ff ff ff ff ff  34 00 00 00 b9 29 63 68 ········ 4····)ch
000001d0 72 6f 6e 69 63 6c 65 2e  6c 61 73 74 41 63 6b 6e ronicle. lastAckn
000001e0 6f 77 6c 65 64 67 65 64  49 6e 64 65 78 52 65 70 owledged IndexRep
000001f0 6c 69 63 61 74 65 64 a7  ff ff ff ff ff ff ff ff licated· ········
00000000 c1 00 00 40 b9 06 68 65  61 64 65 72 b6 08 53 43 ···@··he ader··SC
00000010 51 53 74 6f 72 65 82 aa  00 00 00 cd 77 72 69 74 QStore·· ····writ
00000020 65 50 6f 73 69 74 69 6f  6e 8e 01 00 00 00 00 8d ePositio n·······
00000030 02 00 00 00 00 00 00 00  02 00 00 00 00 00 00 00 ········ ········
00000040 54 01 01 00 00 00 00 00  01 00 00 00 54 01 01 00 T······· ····T···
00000050 c8 69 6e 64 65 78 69 6e  67 b6 0c 53 43 51 53 49 ·indexin g··SCQSI
00000060 6e 64 65 78 69 6e 67 82  4c 00 00 00 ca 69 6e 64 ndexing· L····ind
00000070 65 78 43 6f 75 6e 74 a5  00 10 cc 69 6e 64 65 78 exCount· ···index
00000080 53 70 61 63 69 6e 67 a5  00 01 cb 69 6e 64 65 78 Spacing· ···index
00000090 32 49 6e 64 65 78 8f a7  c8 00 00 00 00 00 00 00 2Index·· ········
000000a0 c9 6c 61 73 74 49 6e 64  65 78 8e 00 00 00 00 a7 ·lastInd ex······
000000b0 00 01 00 00 00 00 00 00  ca 64 61 74 61 46 6f 72 ········ ·dataFor
000000c0 6d 61 74 a1 01 00 00 00  24 80 00 40 b9 0b 69 6e mat····· $··@··in
000000d0 64 65 78 32 69 6e 64 65  78 8e 01 00 00 00 00 8d dex2inde x·······
000000e0 00 10 00 00 00 00 00 00  01 00 00 00 00 00 00 00 ········ ········
000000f0 f0 80 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ········ ········
00000100 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ········ ········
........
000080f0 1c 80 00 40 b9 05 69 6e  64 65 78 8f 8f 8f 8f 8d ···@··in dex·····
00008100 00 10 00 00 00 00 00 00  01 00 00 00 00 00 00 00 ········ ········
00008110 10 01 01 00 00 00 00 00  00 00 00 00 00 00 00 00 ········ ········
00008120 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ········ ········
........
00010110 40 00 00 00 c0 eb 68 65  6c 6c 6f 20 77 6f 72 6c @·····he llo worl
00010120 64 b1 a4 bf a1 41 a5 2e  fb a5 d2 04 a5 d2 e9 a5 d····A·. ········
00010130 2e 16 a5 85 1a 90 c3 f5  48 40 94 ac d4 01 80 05 .······· H@······
00010140 8a 01 02 03 04 80 09 8a  2a 00 00 00 c3 f5 48 40 ········ *·····H@
00010150 d2 04 00 00 07 00 00 00  80 05 8a 05 06 07 08    ········ ·······

Dump the contents of a queue’s metastore (.cq4t file) in canonical hexdump format. Can be useful when analysing queue data and/or for debugging

Returns

A string containing the hexdump

Example

Following on from the dump() example:

// ...
println!("{}", q.dump_metastore());

// prints the following
00000000 b0 00 00 40 b9 06 68 65  61 64 65 72 b6 07 53 54 ···@··he ader··ST
00000010 53 74 6f 72 65 82 9a 00  00 00 c8 77 69 72 65 54 Store··· ···wireT
00000020 79 70 65 b6 08 57 69 72  65 54 79 70 65 ec 42 49 ype··Wir eType·BI
00000030 4e 41 52 59 5f 4c 49 47  48 54 c8 6d 65 74 61 64 NARY_LIG HT·metad
00000040 61 74 61 b6 07 53 43 51  4d 65 74 61 82 60 00 00 ata··SCQ Meta·`··
00000050 00 c4 72 6f 6c 6c b6 08  53 43 51 53 52 6f 6c 6c ··roll·· SCQSRoll
00000060 82 27 00 00 00 c6 6c 65  6e 67 74 68 a6 00 5c 26 ·'····le ngth··\&
00000070 05 c6 66 6f 72 6d 61 74  eb 79 79 79 79 4d 4d 64 ··format ·yyyyMMd
00000080 64 27 46 27 c5 65 70 6f  63 68 a1 00 d7 64 65 6c d'F'·epo ch···del
00000090 74 61 43 68 65 63 6b 70  6f 69 6e 74 49 6e 74 65 taCheckp ointInte
000000a0 72 76 61 6c a1 40 c8 73  6f 75 72 63 65 49 64 a1 rval·@·s ourceId·
000000b0 00 8f 8f 8f 20 00 00 00  b9 14 6c 69 73 74 69 6e ···· ··· ··listin
000000c0 67 2e 68 69 67 68 65 73  74 43 79 63 6c 65 8f a7 g.highes tCycle··
000000d0 f0 4b 00 00 00 00 00 00  24 00 00 00 b9 13 6c 69 ·K······ $·····li
000000e0 73 74 69 6e 67 2e 6c 6f  77 65 73 74 43 79 63 6c sting.lo westCycl
000000f0 65 8e 01 00 00 00 00 a7  f0 4b 00 00 00 00 00 00 e······· ·K······
00000100 1c 00 00 00 b9 10 6c 69  73 74 69 6e 67 2e 6d 6f ······li sting.mo
00000110 64 43 6f 75 6e 74 8f a7  03 00 00 00 00 00 00 00 dCount·· ········
00000120 24 00 00 00 b9 14 63 68  72 6f 6e 69 63 6c 65 2e $·····ch ronicle.
00000130 71 75 65 75 65 2e 6c 6f  63 6b 8e 00 00 00 00 a7 queue.lo ck······
00000140 00 00 00 00 00 00 00 80  24 00 00 00 b9 14 63 68 ········ $·····ch
00000150 72 6f 6e 69 63 6c 65 2e  77 72 69 74 65 2e 6c 6f ronicle. write.lo
00000160 63 6b 8e 00 00 00 00 a7  00 00 00 00 00 00 00 80 ck······ ········
00000170 24 00 00 00 b9 15 63 68  72 6f 6e 69 63 6c 65 2e $·····ch ronicle.
00000180 61 70 70 65 6e 64 2e 6c  6f 63 6b 8f 8f 8f 8f a7 append.l ock·····
00000190 00 00 00 00 00 00 00 80  2c 00 00 00 b9 1d 63 68 ········ ,·····ch
000001a0 72 6f 6e 69 63 6c 65 2e  6c 61 73 74 49 6e 64 65 ronicle. lastInde
000001b0 78 52 65 70 6c 69 63 61  74 65 64 8f 8f 8f 8f a7 xReplica ted·····
000001c0 ff ff ff ff ff ff ff ff  34 00 00 00 b9 29 63 68 ········ 4····)ch
000001d0 72 6f 6e 69 63 6c 65 2e  6c 61 73 74 41 63 6b 6e ronicle. lastAckn
000001e0 6f 77 6c 65 64 67 65 64  49 6e 64 65 78 52 65 70 owledged IndexRep
000001f0 6c 69 63 61 74 65 64 a7  ff ff ff ff ff ff ff ff licated· ········
00000200 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ········ ········
........
000003f0 00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00 ········ ········

When using Queue replication, this call queries the index of the last message acknowledged by at least one replica.

Can be useful for monitoring replication, or (for example) for feedback into a mechanism controlling the replication send window from the primary

Trait Implementations§

Either cxx::kind::Opaque or cxx::kind::Trivial. Read more
§

type Id

A type-level representation of the type’s C++ namespace and type name. Read more

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.