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

An update stream provides a method for updating a specific topic. More...

Data Structures

struct  diffusion_topic_update_stream_params_s
 Structure provided when calling diffusion_topic_update_stream_set More...
 

Typedefs

typedef struct
DIFFUSION_TOPIC_UPDATE_STREAM_T 
DIFFUSION_TOPIC_UPDATE_STREAM_T
 Opaque diffusion topic update stream struct.
 
typedef int(* on_topic_update_stream_result_cb )(DIFFUSION_TOPIC_CREATION_RESULT_T result, void *context)
 Callback from an operation with a topic update stream. More...
 
typedef struct
diffusion_topic_update_stream_params_s 
DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T
 Structure provided when calling diffusion_topic_update_stream_set
 

Enumerations

enum  DIFFUSION_TOPIC_CREATION_RESULT_T { TOPIC_CREATED, TOPIC_EXISTS }
 

Functions

void diffusion_topic_update_stream_set (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_STREAM_T *stream, const BUF_T *value, DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T params)
 Sets the topic to a specified value. More...
 
DIFFUSION_VALUE_Tdiffusion_topic_update_stream_get (const DIFFUSION_TOPIC_UPDATE_STREAM_T *stream)
 Return the latest value of the topic set using this update stream. More...
 
void diffusion_topic_update_stream_validate (SESSION_T *session, const DIFFUSION_TOPIC_UPDATE_STREAM_T *stream, DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T params)
 Validates the update stream. More...
 
void diffusion_topic_update_stream_free (DIFFUSION_TOPIC_UPDATE_STREAM_T *stream)
 Free a memory allocated DIFFUSION_TOPIC_UPDATE_STREAM_T More...
 

Detailed Description

An update stream provides a method for updating a specific topic.

An update stream is associated with a specific topic. The type of the topic must match the type of values passed to the update stream. It can be created with an optional DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T. The existence of the topic, its type and the constraint are validated lazily by the first diffusion_topic_update_stream_set or diffusion_topic_update_stream_validate operation. Subsequent operations issued before the first operation completes will be deferred until the completion of the first operation.

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. An update stream does not prevent other sessions from updating the topic. If exclusive access is required update streams should be used with session locks as constraints.

Once validated an update stream can be invalidated. An invalidated update stream rejects the operations applied to it. The update stream will be invalidated if:

  • the topic is removed
  • another update stream is created for the same topic
  • the topic is updated to a new value by anything other than the stream
  • the session does not have the TOPIC_PERMISSION_UPDATE_TOPIC
  • an operation fails because of cluster repartitioning

Update streams are thread-safe.

Update streams are created using the topic-update feature.

Typedef Documentation

typedef int(* on_topic_update_stream_result_cb)(DIFFUSION_TOPIC_CREATION_RESULT_T result, void *context)

Callback from an operation with a topic update stream.

Parameters
resultThe topic creation result
contextUser-supplied context
Returns
HANDLERS_SUCCESS or HANDLER_FAILURE.

Enumeration Type Documentation

Enumerator
TOPIC_CREATED 

A new topic was created.

TOPIC_EXISTS 

A topic with the same specification already exists.

Function Documentation

void diffusion_topic_update_stream_free ( DIFFUSION_TOPIC_UPDATE_STREAM_T stream)

Free a memory allocated DIFFUSION_TOPIC_UPDATE_STREAM_T

Parameters
streamThe topic update stream to be freed
DIFFUSION_VALUE_T* diffusion_topic_update_stream_get ( const DIFFUSION_TOPIC_UPDATE_STREAM_T stream)

Return the latest value of the topic set using this update stream.

The returned value reflects the last value that has been set, before it is sent to the server.

If the server rejects a set operation, the topic value will not change and this update stream will be invalidated.

diffusion_value_free should be called on the pointer when no longer needed.

Parameters
streamThe stream to get the latest value from
Returns
the cached value of the topic. NULL, if the update stream is in an invalid state
void diffusion_topic_update_stream_set ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_STREAM_T stream,
const BUF_T value,
DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T  params 
)

Sets the topic to a specified value.

The NULL value can only be passed to the value parameter when updating TOPIC_TYPE_STRING, TOPIC_TYPE_INT64 or TOPIC_TYPE_DOUBLE topics.

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.

The first call to this function may fail with DIFF_ERR_NO_SUCH_TOPIC or DIFF_ERR_INCOMPATIBLE_TOPIC. Subsequent calls may fail with DIFF_ERR_INVALID_UPDATE_STREAM. Any call can fail with DIFF_ERR_CLUSTER_REPARTITION, DIFF_ERR_ACCESS_DENIED or DIFF_ERR_NO_SESSION being called to the error callback.

If an update constraint was provided when creating the update stream, the first call to this function may also fail with DIFF_ERR_UNSATISFIED_CONSTRAINT.

If the update stream was created with diffusion_topic_update_create_update_stream_adding_topic, the first call to this function may also fail with DIFF_ERR_INCOMPATIBLE_EXISTING_TOPIC and it will not fail with DIFF_ERR_NO_SUCH_TOPIC being called to the error callback.

If this function fails all subsequent calls to diffusion_topic_update_stream_set will fail with DIFF_ERR_INVALID_UPDATE_STREAM being called to the error callback.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
streamThe update stream to enact the update.
valueThe update value.
paramsParameters describing a topic update stream set request and callbacks handlers which may be invoked in response.
void diffusion_topic_update_stream_validate ( SESSION_T session,
const DIFFUSION_TOPIC_UPDATE_STREAM_T stream,
DIFFUSION_TOPIC_UPDATE_STREAM_PARAMS_T  params 
)

Validates the update stream.

Update streams are validated lazily when diffusion_topic_update_stream_set This function allows the stream to be validated before a value needs to be set.

If the update stream has not been validated yet, calling this function checks the topic exists, the topic type is correct, the constraint is satisfied and the session has permission to update the topic. Once it has been validated calling this function checks the topic has not been removed, no other stream has been created for the topic, the value of the topic has not been changed by anything else and the session still has permission to update the topic.

This function may fail with DIFF_ERR_INCOMPATIBLE_EXISTING_TOPIC, if it is the first call to diffusion_topic_update_stream_validate, diffusion_topic_update_stream_set has not been called and a topic specification was provided when creating the update stream, otherwise it will never fail with this cause.

The first call to this function may fail with DIFF_ERR_NO_SUCH_TOPIC or DIFF_ERR_INCOMPATIBLE_TOPIC. Subsequent calls may fail with a DIFF_ERR_INVALID_UPDATE_STREAM. Any call can fail with DIFF_ERR_CLUSTER_REPARTITION, DIFF_ERR_ACCESS_DENIED or DIFF_ERR_NO_SESSION being called to the error callback.

If an update constraint was provided when creating the update stream, the first call to this function may also fail with DIFF_ERR_UNSATISFIED_CONSTRAINT being called to the error callback.

If the update stream was created with diffusion_topic_update_create_update_stream_adding_topic, the first call to this function may also fail with DIFF_ERR_INCOMPATIBLE_EXISTING_TOPIC and it will not fail with DIFF_ERR_NO_SUCH_TOPIC.

If this function fails all subsequent calls to diffusion_topic_update_stream_set or diffusion_topic_update_stream_validate will fail with DIFF_ERR_INVALID_UPDATE_STREAM.

Parameters
sessionThe session handle. If NULL, this function returns immediately.
streamThe update stream to be validated.
paramsParameters describing a topic update stream validate request and callbacks handlers which may be invoked in response.