Specify synchronization requirements for API functions that access common config streams

[jonnew]

The following API functions must be synchronized be the user. Concurrent access to these functions on different different threads can result in undefined behavior.

oni_get_opt
oni_set_opt
oni_get_driver_opt
oni_set_driver_opt
oni_read_reg
oni_write_reg

This should be specified in the API portion of the spec.

[jonnew]

Proposed Verbiage

Assuming a single, initialized (see oni_init_ctx) context, there are three function groupings that involve physical interaction with hardware.

1. Configuration group

oni_get_opt
oni_set_opt
oni_get_driver_opt
oni_set_driver_opt
oni_read_reg
oni_write_reg

2. Data reading group

oni_read_frame

3. Data writing group

oni_write_frame

The API is not required to be thread safe. Function calls must be manually synchronized by the caller. However, the API, device driver translator, device driver, and hardware must allowing concurrent interaction with all three classes.

[jonnew]

@aacuevas I just want to make sure I'm completely understanding this:

The API should not be assumed to be thread safe

• For instance, if multiple threads are used to read data frames, they must be manually synchronized
• If multiple threads are used for writing frames, they must be manually synchronized
• Etc.
• Basically, individual functions should not be considered thread safe

The API, device driver translator, device driver, and hardware must allow concurrent interaction with all three function classes.

• If we have three threads, we can assign each to a single class from the comment above. They can go nuts within a class without fearing threading issues. Function may error of course, since e.g. going into oni_read_frame() without a context being initialized is not going to work, but there will be no thread or hardware synchronization issues.
• Side effect: oni_ctx must be thread safe or immutable after initialization.

My questions are:

1. Is this interpretation correct?
2. Is this distinction worth specifying or is it potential feature of a oni-compliant API that is outside the spec

[aacuevas]

1. I would say mostly yes. The only nitpick is that this is true, as you wrote in the previous post, for an "initialized context". That is, oni_create_ctx(), oni_init_ctx() and oni_destroy_ctx() are not concurrent with anything at all.

Not sure what you mean with 2