Writer

8 min read

8 min read

8 min read

8 min read

8 min read

8 min read

8 min read

8 min read

8 min read

A writer represents the publisher side of a DataStorm publish–subscribe application. Writers are responsible for publishing the data that readers will receive.

A writer publishes data samples to a specific topic. Each writer is associated with a single topic, but multiple writers can be created for the same topic. The writer’s Key, Value, and UpdateTag template parameters must match the corresponding types of the topic from which it is created.

When a writer is created, DataStorm notifies connected peers. Readers whose configuration matches the writer (topic and keys) will attach so they can receive samples from that writer.

You can optionally assign a name to a writer at creation time. Readers see this name in their connected-writers notifications (getConnectedWriters and onConnectedWriters) and as the origin of each sample it publishes (Sample::getOrigin).

Writers maintain a history queue of samples they have published. Depending on the reader configuration, this history—or part of it—may be transmitted to readers when they connect.

  • Single-key writer Publishes samples for a single key.
  • Multi-key writer Publishes samples for a set of predefined keys.
  • Any-key writer Publishes samples for any key (no keys provided at creation).

Writers can be created using the corresponding writer class constructors or the makeXxxWriter helper functions. When using the helper functions, the compiler automatically deduces the template parameters (Key, Value, and UpdateTag) from the topic.

  • Single-key Attaches to readers that contain the same key, or to filtered readers whose filter matches that key.
  • Multi-key Attaches to readers whose configuration matches at least one of the writer’s keys, or to filtered readers whose filter matches any of those keys.
  • Any-key Attaches to all readers of the topic, since any key can be published.
C++
// Constructor
Topic<string, float> temperatures{node, "temperatures"};
SingleKeyWriter<string, float> writer{
temperatures,
"floor1/kitchen",
"kitchen-writer"};

Or

C++
// Helper (template params deduced)
Topic<string, float> temperatures{node, "temperatures"};
auto writer = makeSingleKeyWriter(
temperatures,
"floor1/kitchen",
"kitchen-writer");
C++
// Constructor
Topic<string, float> temperatures{node, "temperatures"};
MultiKeyWriter<string, float> writer{
temperatures,
{"floor1/kitchen", "floor1/living-room"},
"first-floor-writer"};

Or

C++
// Helper (template params deduced)
Topic<string, float> temperatures{node, "temperatures"};
auto writer = makeMultiKeyWriter(
temperatures,
{"floor1/kitchen", "floor1/living-room"},
"first-floor-writer");
C++
// Constructor: empty key set
Topic<string, float> temperatures{node, "temperatures"};
MultiKeyWriter<string, float> writer{temperatures, {}, "temperature-writer"};

Or

C++
// Helper (template params deduced)
Topic<string, float> temperatures{node, "temperatures"};
auto writer = makeAnyKeyWriter(temperatures, "temperature-writer");

Writers are responsible for publishing data samples to a topic.

A SingleKeyWriter provides the following methods for publishing samples:

  • add — publishes an Add sample.
  • update — publishes an Update sample.
  • remove — publishes a Remove sample (no value is included).
  • partialUpdate — returns a function that can be used to publish partial update samples for a given update tag.
C++
Topic<string, float> temperatures{node, "temperatures"};
temperatures.setUpdater<float>("increment", [](float& value, float delta) { value += delta; });
SingleKeyWriter<string, float> writer{
temperatures,
"floor1/kitchen",
"kitchen-writer"};
// Publish an Add sample
writer.add(21.0f);
// Publish an Update sample
writer.update(20.0f);
// Publish a PartialUpdate sample with the "increment" updater
auto increment = writer.partialUpdate<float>("increment");
increment(0.5f);
// Publish a Remove sample. Remove samples don’t include a value
writer.remove();

The template parameter of partialUpdate must match the type used to register the updater with Topic::setUpdater. The key must have a current value when you call the returned function: this writer gave it a value with add or update, and did not remove it since.

The MultiKeyWriter—used for both multi-key and any-key writers—provides the same four methods. add, update, and remove take an additional key parameter, and the function returned by partialUpdate takes the key and the update value.

  • add — publishes an Add sample for the given key.
  • update — publishes an Update sample for the given key.
  • remove — publishes a Remove sample for the given key.
  • partialUpdate — returns a function that can be used to publish partial update samples for the given update tag.
C++
Topic<string, float> temperatures{node, "temperatures"};
MultiKeyWriter<string, float> writer{
temperatures,
{"floor1/kitchen", "floor1/living-room"},
"first-floor-writer"};
// Publish an Add sample
writer.add("floor1/kitchen", 21.0f);
// Publish an Update sample
writer.update("floor1/kitchen", 20.0f);
// Publish a PartialUpdate sample with the "increment" updater
auto increment = writer.partialUpdate<float>("increment");
increment("floor1/kitchen", 0.5f);
// Publish a Remove sample
writer.remove("floor1/kitchen");

Writer behavior is configurable through the DataStorm::WriterConfig class. Configuration can be provided at multiple levels, allowing both global defaults and per-writer customization.

You can set:

Precedence: lower levels override higher ones (per-writer config > topic defaults > global properties). DataStorm takes each option you leave unset from the next level.

Specifies the maximum number of samples kept in the writer’s history queue. When the queue is full, the oldest samples are discarded. A negative value, the default, sets no limit; 0 keeps no samples. Note that with the default clearHistory policy, OnAll, the queue holds at most one sample.

Specifies how long a sample stays in the writer’s history queue, in milliseconds. DataStorm removes samples older than this duration from the queue. 0, the default, or a negative value sets no age limit.

Controls when the writer’s sample queue is cleared, based on sample events (ClearHistoryPolicy). DataStorm clears the queue before it queues the sample that triggers the clearing, so the queue then holds only this sample. Default: OnAll.

  • OnAdd: Clears the queue when publishing an Add sample.
  • OnRemove: Clears the queue when publishing a Remove sample.
  • OnAll: Clears the queue when publishing any sample.
  • OnAllExceptPartialUpdate: Clears the queue when publishing any sample except a PartialUpdate.
  • Never: Never clears the queue automatically.

Specifies the priority of the writer. Default: 0. Readers can be configured with a discard policy (see DiscardPolicy::Priority) to accept only the samples from the writers with the highest priority among the writers connected for the sample's key.

Writers provide methods and listener callbacks to coordinate with connected readers.

Use onConnectedKeys(initCallback, updateCallback) to register callbacks that monitor connected keys, replacing any callbacks registered before:

  • DataStorm calls initCallback once with the initial set of connected keys.
  • DataStorm calls updateCallback whenever a key is connected or disconnected.

Use onConnectedReaders(initCallback, updateCallback) to register callbacks that monitor connected readers, replacing any callbacks registered before:

  • DataStorm calls initCallback once with the initial set of connected readers.
  • DataStorm calls updateCallback whenever a reader connects or disconnects.