JLS Threaded Writer

group Threaded writer

JLS threaded writer.

This module wraps writer. For normal operation while recording signals, prefer this threaded writer over writer.

Errors: each call validates its arguments synchronously, and a validation error changes nothing. The writer thread performs the writes, so their errors are asynchronous. The first asynchronous error latches: the thread keeps draining its queue but drops all data messages, and every later jls_twr_* call, jls_twr_flush(), and jls_twr_close() returns the latched error. Call jls_twr_flush() to confirm that all queued writes succeeded.

Enums

enum jls_twr_flag_e

The threaded writer flags.

Values:

enumerator JLS_TWR_FLAG_DROP_ON_OVERFLOW

Drop on overflow when set, block otherwise.

Functions

int32_t jls_twr_open(struct jls_twr_s **instance, const char *path)

Open a JLS file for writing.

Call jls_twr_close() when done.

Parameters:

• instance – [out] The JLS writer instance.

• path – The JLS file path.

Returns:

0 or error code.

int32_t jls_twr_close(struct jls_twr_s *self)

Close a JLS file.

Close writes all queued messages before closing the file, even when the queue is full. After a latched error, the queued data messages are dropped and the file is left not properly closed, so jls_rd_open() recovers the data written before the error. See jls_wr_close().

Parameters:

self – The JLS writer instance from jls_twr_open(), which is always freed.

Returns:

0, the latched error, or the jls_wr_close() error.

uint32_t jls_twr_flags_get(struct jls_twr_s *self)

Parameters:

• Get – threaded writer flags.

• self – The JLS writer instance from jls_twr_open().

• flags – The jls_twr_flag_e bits.

Returns:

0 or error code.

int32_t jls_twr_flags_set(struct jls_twr_s *self, uint32_t flags)

Parameters:

• Set – threaded writer flags.

• self – The JLS writer instance from jls_twr_open().

• flags – The jls_twr_flag_e bits.

Returns:

0 or error code.

int32_t jls_twr_flush(struct jls_twr_s *self)

Flush a JLS file to disk.

See jls_wr_flush() for the durability provided.

Parameters:

self – The JLS writer instance from jls_twr_open().

Returns:

0 when all previously queued messages were written and flushed, the latched error, JLS_ERROR_BUSY if the flush could not be queued, or JLS_ERROR_TIMED_OUT.

int32_t jls_twr_source_def(struct jls_twr_s *self, const struct jls_source_def_s *source)

Define a new source.

This JLS file format supports multiple sources, which are usually different instruments. Each source can provide multiple signals.

Parameters:

• self – The JLS writer instance.

• source – The source definition.

Returns:

0 or error code.

int32_t jls_twr_signal_def(struct jls_twr_s *self, const struct jls_signal_def_s *signal)

Define a new signal.

Parameters:

• self – The JLS writer instance.

• signal – The signal definition.

Returns:

0 or error code.

int32_t jls_twr_user_data(struct jls_twr_s *self, uint16_t chunk_meta, enum jls_storage_type_e storage_type, const uint8_t *data, uint32_t data_size)

Add arbitrary user data.

Parameters:

• self – The writer instance.

• chunk_meta – The arbitrary data. Bits 15:12 are reserved and must be 0 (else JLS_ERROR_PARAMETER_INVALID), but bits 11:0 may be assigned by the application.

• storage_type – The storage type for data, which must be a jls_storage_type_e value.

• data – The user data to store.

• data_size – The size of data in bytes. For STRING and JSON, 0 means strlen(data) + 1, and a nonzero size must include the NUL.

Returns:

0 or error code. JLS_ERROR_TOO_BIG when the message exceeds the internal queue.

int32_t jls_twr_fsr(struct jls_twr_s *self, uint16_t signal_id, int64_t sample_id, const void *data, uint32_t data_length)

Write fixed-rate sample data to a signal.

Parameters:

• self – The JLS writer instance.

• signal_id – The signal id.

• sample_id – The sample id for data[0].

• data – The sample data array. Data must be packed with no spacing between samples. u1 stores 8 samples per byte, and u4 stores 2 samples per byte.

• data_length – The length of data in samples.

Returns:

0 or error code. JLS_ERROR_TOO_BIG when the data exceeds the internal queue (about 64 MiB).

int32_t jls_twr_fsr_f32(struct jls_twr_s *self, uint16_t signal_id, int64_t sample_id, const float *data, uint32_t data_length)

Write sample data to a float32 FSR signal.

Parameters:

• self – The JLS writer instance.

• signal_id – The signal id.

• sample_id – The sample id for data[0].

• data – The sample data array.

• data_length – The length of data in floats (bytes / 4).

Returns:

0 or error code

int32_t jls_twr_fsr_omit_data(struct jls_twr_s *self, uint16_t signal_id, uint32_t enable)

Omit level 0 data chunks from the signal’s stream.

Enable is delayed by one sample block to ensure any pending data is writen. Disable takes effect immediately.

On read, the level 0 data is reconstructed using the summaries.

When enabled, the writer omits a data chunk only when the signal’s data type is 8 bits or less (u1, u4, u8, i4, i8) and every sample in the chunk has the same value. The setting has no effect on other data types.

Parameters:

• self – The JLS writer instance

• signal_id – The signal id.

• enable – 0 to disable (default), 1 to enable.

Returns:

0 or error code.

int32_t jls_twr_annotation(struct jls_twr_s *self, uint16_t signal_id, int64_t timestamp, float y, enum jls_annotation_type_e annotation_type, uint8_t group_id, enum jls_storage_type_e storage_type, const uint8_t *data, uint32_t data_size)

Add an annotation to a signal.

Parameters:

• self – The writer instance.

• signal_id – The signal id.

• timestamp – The x-axis timestamp in sample_id for FSR and UTC for VSR.

• y – The y-axis value or NAN to automatically position.

• annotation_type – The annotation type.

• group_id – The optional group identifier. If unused, set to 0.

• storage_type – The storage type.

• data – The data for the annotation.

• data_size – The length of data in bytes. For STRING and JSON, 0 means strlen(data) + 1, and a nonzero size must include the NUL.

Returns:

0 or error code. JLS_ERROR_TOO_BIG when the message exceeds the internal queue.

int32_t jls_twr_utc(struct jls_twr_s *self, uint16_t signal_id, int64_t sample_id, int64_t utc)

Add a mapping from sample_id to UTC timestamp for an FSR signal.

Parameters:

• self – The writer instance.

• signal_id – The signal id.

• sample_id – The sample_id for FSR.

• utc – The UTC timestamp.

Returns:

0 or error code.