update-stream-builder.h File Reference

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

Typedefs
typedef struct DIFFUSION_UPDATE_STREAM_BUILDER_T	DIFFUSION_UPDATE_STREAM_BUILDER_T
	Opaque Diffusion Update Stream Builder.

Functions
DIFFUSION_UPDATE_STREAM_BUILDER_T *	diffusion_update_stream_builder_init ()
	Initialize a new update stream builder. More...
bool	diffusion_update_stream_builder_reset (DIFFUSION_UPDATE_STREAM_BUILDER_T *builder, DIFFUSION_API_ERROR *error)
	Resets the builder to its default parameters. More...
bool	diffusion_update_stream_builder_topic_specification (DIFFUSION_UPDATE_STREAM_BUILDER_T *builder, const TOPIC_SPECIFICATION_T *specification, DIFFUSION_API_ERROR *error)
	Specifies a topic specification for this update stream. More...
bool	diffusion_update_stream_builder_update_constraint (DIFFUSION_UPDATE_STREAM_BUILDER_T *builder, const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *constraint, DIFFUSION_API_ERROR *error)
	Specifies an update constraint for this update stream. More...
void	diffusion_update_stream_builder_free (DIFFUSION_UPDATE_STREAM_BUILDER_T *builder)
	Free an update stream builder. More...
DIFFUSION_TOPIC_UPDATE_STREAM_T *	diffusion_update_stream_builder_create_update_stream (DIFFUSION_UPDATE_STREAM_BUILDER_T *builder, const char *topic_path, DIFFUSION_DATATYPE datatype, DIFFUSION_API_ERROR *error)
	Creates an update stream to use for updating a specific topic. More...
DIFFUSION_RECOVERABLE_UPDATE_STREAM_T *	diffusion_update_stream_builder_create_recoverable_update_stream (DIFFUSION_UPDATE_STREAM_BUILDER_T *builder, const char *topic_path, DIFFUSION_DATATYPE datatype, DIFFUSION_RETRY_STRATEGY_T *retry_strategy, DIFFUSION_API_ERROR *error)
	Creates an update stream to use for updating a specific topic with recovery capabilities. 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 PATH_PERMISSION_UPDATE_TOPIC
• an operation fails because of cluster repartitioning

Update streams are thread-safe.

Update streams are created using the topic-update feature.

Function Documentation

DIFFUSION_RECOVERABLE_UPDATE_STREAM_T* diffusion_update_stream_builder_create_recoverable_update_stream	(	DIFFUSION_UPDATE_STREAM_BUILDER_T *	builder,
		const char *	topic_path,
		DIFFUSION_DATATYPE	datatype,
		DIFFUSION_RETRY_STRATEGY_T *	retry_strategy,
		DIFFUSION_API_ERROR *	error
	)

Creates an update stream to use for updating a specific topic with recovery capabilities.

The type of the topic being updated must match the datatype.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required, update streams should be used with session locks as constraints.

Streams are validated lazily when the first diffusion_topic_update_stream_set or diffusion_topic_update_stream_validate operation is completed. Once validated, a stream can be invalidated, after which it rejects future updates.

Parameters

builder	the update stream builder.
topic_path	the path to the topic.
datatype	the topic's datatype.
retry_strategy	the retry strategy for how long to wait between and how many retry attempts.
error	populated if an error occurrs. Can be NULL.

Returns

the recoverable update stream or NULL if an error occurred.

Since

6.10

DIFFUSION_TOPIC_UPDATE_STREAM_T* diffusion_update_stream_builder_create_update_stream	(	DIFFUSION_UPDATE_STREAM_BUILDER_T *	builder,
		const char *	topic_path,
		DIFFUSION_DATATYPE	datatype,
		DIFFUSION_API_ERROR *	error
	)

Creates an update stream to use for updating a specific topic.

The type of the topic being updated must match the datatype.

Update streams send a sequence of updates for a specific topic. The updates may be delivered to the server as binary deltas. They do not provide exclusive access to the topic. If exclusive access is required, update streams should be used with session locks as constraints.

Streams are validated lazily when the first diffusion_topic_update_stream_set or diffusion_topic_update_stream_validate operation is completed. Once validated, a stream can be invalidated, after which it rejects future updates.

Parameters

builder	the update stream builder.
topic_path	the path to the topic.
datatype	the topic's datatype.
error	populated if an error occurrs. Can be NULL.

Returns

the update stream or NULL if an error occurred.

Since

6.9

void diffusion_update_stream_builder_free

(

DIFFUSION_UPDATE_STREAM_BUILDER_T *

builder

)

Free an update stream builder.

Parameters

builder

the update stream builder.

Since

6.9

DIFFUSION_UPDATE_STREAM_BUILDER_T* diffusion_update_stream_builder_init

(

)

Initialize a new update stream builder.

diffusion_update_stream_builder_free should be called on this pointer when no longer needed.

Returns

the update stream builder.

Since

6.9

bool diffusion_update_stream_builder_reset	(	DIFFUSION_UPDATE_STREAM_BUILDER_T *	builder,
		DIFFUSION_API_ERROR *	error
	)

Resets the builder to its default parameters.

Parameters

builder	the update stream builder.
error	populated if an error occurrs. Can be NULL.

Returns

true if successul, false if an error occurred.

Since

6.9

bool diffusion_update_stream_builder_topic_specification	(	DIFFUSION_UPDATE_STREAM_BUILDER_T *	builder,
		const TOPIC_SPECIFICATION_T *	specification,
		DIFFUSION_API_ERROR *	error
	)

Specifies a topic specification for this update stream.

If a topic does not exist at the topic path, one will be created using the topic specification when the update stream is validated. If a topic does exist, its topic specification must match, otherwise the operation will fail.

Parameters

builder	the update stream builder.
specification	the required specification of the topic.
error	populated if an error occurrs. Can be NULL.

Returns

true if successul, false if an error occurred.

Since

6.9

bool diffusion_update_stream_builder_update_constraint	(	DIFFUSION_UPDATE_STREAM_BUILDER_T *	builder,
		const DIFFUSION_TOPIC_UPDATE_CONSTRAINT_T *	constraint,
		DIFFUSION_API_ERROR *	error
	)

Specifies an update constraint for this update stream.

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
• part of the current value of the topic being updated

Constraint is Unconstrained by default. Calling this method with a NULL parameter resets the constraint for this builder.

Parameters

builder	the update stream builder.
constraint	the constraint that must be satistied for the update stream to be validated.
error	populated if an error occurrs. Can be NULL.

Returns

true if successul, false if an error occurred.

Since

6.9