Diffusion C API  6.3.3
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
topic-update.h File Reference

This feature 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...
 

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 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.
 

Functions

void diffusion_topic_update_set (SESSION_T *session, DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
void diffusion_topic_update_set_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
void diffusion_topic_update_add_and_set (SESSION_T *session, DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
void diffusion_topic_update_add_and_set_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_TOPIC_UPDATE_ADD_AND_SET_PARAMS_T params)
 Sets the topic to a specified value. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream (SESSION_T *session, const char *topic_path, DIFFUSION_DATATYPE datatype)
 Creates an update strean to use for updating a specific topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, const char *topic_path, DIFFUSION_DATATYPE datatype)
 Creates an update stream to use for updating a specific topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream_adding_topic (SESSION_T *session, const char *topic_path, const TOPIC_SPECIFICATION_T *specification, DIFFUSION_DATATYPE datatype, DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T params)
 Creates an update stream to use for creating and updating a specific topic. More...
 
DIFFUSION_TOPIC_UPDATE_STREAM_Tdiffusion_topic_update_create_update_stream_adding_topic_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, const char *topic_path, const TOPIC_SPECIFICATION_T *specification, DIFFUSION_DATATYPE datatype, DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T params)
 Creates an update stream to use for creating and updating a specific topic. More...
 

Detailed Description

This feature 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.

  • Update streams

An update stream is created for a specific topic. 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.

  • Constraints

Constraints can be applied to the setting of a value and creation of an update stream. Constraints describe a condition that must be satisfied for the operation to succeed. The constraints are evaluated on the server. The available constraints: are an active session lock, the absence of a topic, the current value of the topic being updated, and a part of the current value of the topic being updated.

  • Removing values

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

  • Adding topics

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.

  • Access control

To update a topic a session needs TOPIC_PERMISSION_UPDATE_TOPIC permission for the topic path. To create a topic a session needs TOPIC_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 Documentation

typedef int(* on_topic_update_set_success_cb)(void *context)

Callback when a topic set is successful.

Parameters
contextUser supplied context passed in from DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.
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.

Parameters
resultThe 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.
contextUser supplied context passed in from DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.