003 Granularity of read access of data clients

  • Status: accepted
  • Deciders: partners

Context and Problem Statement

Due to a very heterogenous system landscape with multiple different data sources we need to define a read access API which can be realized for all data sources.

Decision Drivers

  • supportability: data clients can be easily implemented by a sensor/tool manufacturer
  • usability: allow easy access to multiple values
  • consistency: enable synchronized/consistent access to related values

Considered Options

  • Only single values/fields can be read
  • Complete state is read at once
  • Select values/fields to read

Decision Outcome

Select values/fields to read

This option was choosen even though it might require more effort when implementing data clients to have a simple and at the same time more versatile API.

Positive Consequences

  • the other two options can be easily covered by corresponding selections over single fields or the complete state
  • data clients are responsible to return a consistent state of all the variables requested while the TEK is responsible to request all variables which need to be consistent with only one call

Negative Consequences

  • a slightly increased complexity in the implementation of the DC (compared to the first option), especially concerning error handling

Pros and Cons of the Options

Only single values/fields can be read

The data client provides a callback for single fields.

  bool (*data_client_read_callback)(
            data_client dc, 
            field_handle field,
            struct read_result* result);
  • Good, because read access is simple
  • Good, because data client must not handle consistent read access
  • Good, because read error handling is field specific
  • Bad, because overhead in TE when accessing multiple fields
  • Bad, because additional APIs are required to enable consistent access to multiple values (i.e. some kind of transaction mechanism)

Complete state is read at once

The data client provides a callback for the complete current state of the data source.

  bool (*data_client_read_callback)(
            data_client dc,
            struct read_result** results,
            int* read_results_count);
  • Good, because no separate synchronization is required in the API
  • Bad, because can return more data than needed by the TEK
  • Bad, because data client must handle read access synchronization
  • Bad, because error handling for read errors is more complex

Select values/fields to read

The data client provides a callback which supports selection of values/fields to read.

  bool (*data_client_read_callback)(
            data_client dc, 
            field_handle* fields,
            size_t fields_size,
            struct read_result* results);
  • Good, because no separate synchronization is required in the API
  • Good, because returns exactly the data needed by the TEK
  • Good, because single field read access can be covered by the same callback
  • Good, because the memory management is done completely in the TEK
  • Bad, because data client must handle read access synchronization
  • Bad, because error handling for read errors is more complex