2.4.3.3 Writing¶
Functions that may only be called by the write thread.
-
struct ZixRingTransaction¶
A transaction for writing data in multiple parts.
The simple
zix_ring_write()
can be used to write an atomic message that will immediately be visible to the reader, but transactions allow data to be written in several chunks before being “committed” and becoming readable. This can be useful for things like prefixing messages with a header without needing an allocated buffer to construct the “packet”.The contents of this structure are an implementation detail and must not be manipulated by the user.
-
uint32_t read_head¶
Read head at the start of the transaction.
-
uint32_t write_head¶
Write head if the transaction were committed.
-
uint32_t read_head¶
-
uint32_t zix_ring_write_space(const ZixRing *ring)¶
Return the number of bytes available for writing.
This function returns at most one less than the ring’s buffer size.
-
uint32_t zix_ring_write(ZixRing *ring, const void *src, uint32_t size)¶
Write data to the ring.
This writes a contiguous input buffer of bytes to the ring.
- Parameters:
ring – The ring to write data to.
src – The buffer to read data from.
size – The number of bytes to read from
src
and write toring
.
- Returns:
The number of bytes written, which is either
size
on success, or zero on failure.
-
ZixRingTransaction zix_ring_begin_write(ZixRing *ring)¶
Begin a write.
The returned transaction is initially empty. Data can be written to it by calling
zix_ring_amend_write()
one or more times, then finishing withzix_ring_commit_write()
.Note that the returned “transaction” is not meant to be long-lived: a call to this function should be (more or less) immediately followed by calls to
zix_ring_amend_write()
then a call tozix_ring_commit_write()
.- Parameters:
ring – The ring to write data to.
- Returns:
A new empty transaction.
-
ZixStatus zix_ring_amend_write(ZixRing *ring, ZixRingTransaction *tx, const void *src, uint32_t size)¶
Amend the current write with some data.
The data is written immediately after the previously amended data, as if they were written contiguously with a single write call. This data is not visible to the reader until
zix_ring_commit_write()
is called.If any call to this function returns an error, then the transaction is invalid and must not be committed. No cleanup is necessary for an invalid transaction. Any bytes written while attempting the transaction will remain in the free portion of the buffer and be overwritten by subsequent writes.
- Parameters:
ring – The ring this transaction is writing to.
tx – The active transaction, from
zix_ring_begin_write()
.src – Pointer to the data to write.
size – Length of data to write in bytes.
- Returns:
ZixStatus.ZIX_STATUS_NO_MEM
orZixStatus.ZIX_STATUS_SUCCESS
.
-
ZixStatus zix_ring_commit_write(ZixRing *ring, const ZixRingTransaction *tx)¶
Commit the current write.
This atomically updates the state of the ring, so that the reader will observe the data written during the transaction.
This function usually shouldn’t be called for any transaction which
zix_ring_amend_write()
returned an error for.- Parameters:
ring – The ring this transaction is writing to.
tx – The active transaction, from
zix_ring_begin_write()
.
- Returns: