JLS Threaded Writer

group jls_threaded_writer

JLS threaded writer.

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

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.

Parameters:

self – The JLS writer instance from jls_twr_open().

Returns:

0 or error code.

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.

Parameters:

self – The JLS writer instance from jls_twr_open().

Returns:

0 or error code.

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, but bits 11:0 may be assigned by the application.

  • storage_type – The storage type for data.

  • data – The user data to store.

  • data_size – The size of data for JLS_STORAGE_TYPE_BINARY. Ignored for all other storage types.

Returns:

0 or error code.

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

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.

As of Sep 2023, this setting is ignored for u1, u4, u8, i4, and i8 FSR data types. These data types are omitted whenever the payload contains a constant data value regardless of this setting.

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 for JLS_STORAGE_TYPE_BINARY storage_type. Set to 0 for all other storage types.

Returns:

0 or error code.

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.