 |
Diffusion C API
6.10.3
|
|
Diffusion C API
6.10.3
|
Provides a client session with the ability to update topics. More...
Data Structures | |
| struct | diffusion_topic_update_params_s |
| Structure describing a topic set request. More... | |
| struct | diffusion_topic_update_add_and_set_params_s |
| Structure describing a topic add and set request. More... | |
| struct | diffusion_apply_json_patch_params_s |
| Structure describing a JSON patch application request. More... | |
Typedefs | |
| typedef int(* | on_topic_update_set_success_cb )(void *context) |
| Callback when a topic set is successful. More... | |
| typedef int(* | on_topic_update_topic_creation_cb )(DIFFUSION_TOPIC_CREATION_RESULT_T result, void *context) |
| Callback when a topic add and set is successful. More... | |
| typedef int(* | on_json_patch_result_cb )(const DIFFUSION_JSON_PATCH_RESULT_T *result, void *context) |
| Callback with the result of the JSON patch operation. More... | |
|
typedef struct diffusion_topic_update_params_s | DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T |
| Structure describing a topic set request. | |
|
typedef struct diffusion_topic_update_add_and_set_params_s | DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T |
| Structure describing a topic add and set request. | |
|
typedef struct diffusion_apply_json_patch_params_s | DIFFUSION_APPLY_JSON_PATCH_PARAMS_T |
| Structure describing a JSON patch application request. | |
Provides a client session with the ability to update topics.
Topics can be set to new values using stateless diffusion_topic_update_set operations or a DIFFUSION_TOPIC_UPDATE_STREAM_T. Both ensure that new values are applied safely to appropriate topics.
An update stream is created for a specific topic. An update stream builder can be obtained using the diffusion_update_stream_builder_init method. The type of the topic must match the type of values passed to the update stream. An update stream can be used to send any number of updates. It sends a sequence of updates for a specific topic to the server. If supported by the data type, updates will be sent to the server as a stream of binary deltas.
Update streams have additional ways of failing compared to stateless set operations but when used repeatedly have lower overheads. This is because update streams maintain a small amount of state that reduces the overhead of operations but can become invalid for example, if the topic is deleted, or some other session updates the topic value.
By default, update streams use a form of optimistic locking. An update stream can update its topic incrementally as long as nothing else updates the topic. If the topic is updated independently (for example, by another session, or by the current session via set or a different update stream), then the next update performed by the update stream will result in an DIFF_ERR_INVALID_UPDATE_STREAM.
Applications can chose to use collaborative locking to coordinate exclusive access to a topic. To follow this pattern acquire a DIFFUSION_SESSION_LOCK_T, and use it with a diffusion_topic_update_constraint_locked constraint. The application is responsible for designing a locking scheme which determines which lock is required to access a particular topic, and for ensuring that all parts of the application that update the topic follow this scheme. Lock constraints and an application locking scheme can also ensure a sequence of set operations has exclusive access to the topic.
When a TOPIC_TYPE_STRING, TOPIC_TYPE_INT64, or TOPIC_TYPE_DOUBLE topic is set to null, the topic will be updated to have no value. If a previous value was present subscribers will receive a notification that the new value is null. New subscribers will not receive a value notification. Attempting to set any other type of topic to NULL will cause the error callback to be called with DIFF_ERR_INVALID_DATA
When setting a value using either stateless operations or update streams it is possible to add a topic if one is not present. This is done using the diffusion_topic_update_add_and_set function or providing a topic specification when creating the update stream. If a topic exists these methods will update the existing topic.
To update a topic a session needs PATH_PERMISSION_UPDATE_TOPIC permission for the topic path. To create a topic a session needs PATH_PERMISSION_MODIFY_TOPIC permission for the topic path. Requests that combine adding a topic and setting the value such as diffusion_topic_update_add_and_setrequire both permissions.
| typedef int(* on_json_patch_result_cb)(const DIFFUSION_JSON_PATCH_RESULT_T *result, void *context) |
Callback with the result of the JSON patch operation.
| result | The JSON patch result. |
| context | User supplied context passed in from DIFFUSION_APPLY_JSON_PATCH_PARAMS_T |
| typedef int(* on_topic_update_set_success_cb)(void *context) |
Callback when a topic set is successful.
| context | User supplied context passed in from DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T |
| typedef int(* on_topic_update_topic_creation_cb)(DIFFUSION_TOPIC_CREATION_RESULT_T result, void *context) |
Callback when a topic add and set is successful.
| result | The topic creation result of the add and set operation. Will be either TOPIC_CREATED showing that the topic was created and then updated. Or TOPIC_EXISTS showing that the topic already exists and was subsequently updated. |
| context | User supplied context passed in from DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T |
| int diffusion_json_patch_result_get_first_failure | ( | const DIFFUSION_JSON_PATCH_RESULT_T * | result | ) |
Return the index of the first failure in the JSON patch.
| result | The JSON patch result. |
result is NULL. 
1.8.5