2.4.3.4 Writing — Zix 0.8.2 documentation

# 2.4.3.4 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.

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` or `ZixStatus.ZIX_STATUS_SUCCESS`.

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 with `zix_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 to `zix_ring_commit_write()`.

  Parameters:

    - ring – The ring to write data to.

  Returns:

    A new empty transaction.

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:

    `ZixStatus.ZIX_STATUS_SUCCESS`.

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 to `ring`.

  Returns:

    The number of bytes written, which is either `size` on success, or zero on failure.

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.