topic-update.h File Reference

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

Functions
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.
void	diffusion_topic_update_set (SESSION_T *session, DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T params)
	Sets the topic to a specified value.
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.
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.
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.
bool	diffusion_apply_json_patch (SESSION_T *session, DIFFUSION_APPLY_JSON_PATCH_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Applies a JSON Patch to a JSON topic.
bool	diffusion_apply_json_patch_with_constraint (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_APPLY_JSON_PATCH_PARAMS_T params, DIFFUSION_API_ERROR *api_error)
	Applies a JSON Patch to a JSON topic.
	DEPRECATED (DIFFUSION_TOPIC_UPDATE_STREAM_T *diffusion_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.
	DEPRECATED (DIFFUSION_TOPIC_UPDATE_STREAM_T *diffusion_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.
	DEPRECATED (DIFFUSION_TOPIC_UPDATE_STREAM_T *diffusion_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.
	DEPRECATED (DIFFUSION_TOPIC_UPDATE_STREAM_T *diffusion_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.

Detailed Description

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

• 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 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 Documentation

on_json_patch_result_cb

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.

Parameters

result	The JSON patch result.
context	User supplied context passed in from DIFFUSION_APPLY_JSON_PATCH_PARAMS_T

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

on_topic_update_set_success_cb

typedef int(* on_topic_update_set_success_cb) (void *context)

Callback when a topic set is successful.

Parameters

context

User supplied context passed in from DIFFUSION_TOPIC_UPDATE_SET_PARAMS_T

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

on_topic_update_topic_creation_cb

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

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

Returns

HANDLERS_SUCCESS or HANDLER_FAILURE.

Function Documentation

diffusion_json_patch_result_get_first_failure()

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.

Parameters

result

The JSON patch result.

Returns

the index of the first failure in the JSON patch. -1 if there were no failures or result is NULL.