\Drupal\strata\Journal JournalInterface

The append-only log a capture writes to and a flush drains.

Capture happens inside a web request, so the write here has to be cheap: an append and nothing else. Compression, encryption, framing and the network all happen later, in the flush, off the request path. The semantic capture that produces an operation measures about 7 microseconds, and the append is the only other cost on the request.

A journal is durable but not permanent. Once a flush has sealed a window into a segment the operations are redundant and are trimmed. What makes it necessary rather than a buffer is that a request can end, or crash, between the capture and the flush.

Summary

Methods

Constants

append()
read()
trim()
pending()
pendingBytes()
oldest()
clear()

No public constants found

File: src/Journal/JournalInterface.php
Package: \Application
See also

Methods

append()

append(\Drupal\strata\Journal\JournalOp  $operation, string|null  $payload = null) : \Drupal\strata\Journal\JournalOp

Appends an operation and its payload.

The sequence on the supplied operation is ignored; the journal assigns it, because only the journal can order two concurrent requests.

Parameters

\Drupal\strata\Journal\JournalOp	$operation	The operation to append.
string\|null	$payload	The value the operation captured, or NULL for an operation that carries none.

Throws

\RuntimeException: When the append fails.

Returns

\Drupal\strata\Journal\JournalOp —

The operation as appended, carrying its assigned sequence.

read()

read(int  $limit = 5000) : list<array{operation: \Drupal\strata\Journal\JournalOp, payload: string|null}>

Reads a window of operations in capture order, oldest first.

Parameters

int

$limit

Most operations to return.

Throws

\RuntimeException: When the read fails.

Returns

list —

Operations paired with their payloads.

trim()

trim(int  $throughSequence) : int

Removes every operation up to and including a sequence.

Called after a flush has sealed a segment. Trimming is separate from reading so a flush that fails leaves the window intact and can be retried.

Parameters

int

$throughSequence

The highest sequence to remove.

Throws

\RuntimeException: When the trim fails.

Returns

int —

How many operations were removed.

pending()

pending() : int

How many operations are waiting.

Returns

int —

The pending count.

pendingBytes()

pendingBytes() : int

Bytes of payload waiting.

Returns

int —

The pending payload total.

oldest()

oldest() : int|null

Unix microseconds of the oldest waiting operation.

Returns

int|null —

The microtime, or NULL when nothing is waiting.

clear()

clear() : int

Removes everything without flushing it.

Returns

int —

How many operations were removed.