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.
Writer Types
- 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.
Attachment Behavior
- 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.
Single-Key Writer
// ConstructorTopic<string, float> temperatures{node, "temperatures"};SingleKeyWriter<string, float> writer{ temperatures, "floor1/kitchen", "kitchen-writer"};Or
// Helper (template params deduced)Topic<string, float> temperatures{node, "temperatures"};auto writer = makeSingleKeyWriter( temperatures, "floor1/kitchen", "kitchen-writer");Multi-Key Writer
// ConstructorTopic<string, float> temperatures{node, "temperatures"};MultiKeyWriter<string, float> writer{ temperatures, {"floor1/kitchen", "floor1/living-room"}, "first-floor-writer"};Or
// Helper (template params deduced)Topic<string, float> temperatures{node, "temperatures"};auto writer = makeMultiKeyWriter( temperatures, {"floor1/kitchen", "floor1/living-room"}, "first-floor-writer");Any-Key Writer
// Constructor: empty key setTopic<string, float> temperatures{node, "temperatures"};MultiKeyWriter<string, float> writer{temperatures, {}, "temperature-writer"};Or
// Helper (template params deduced)Topic<string, float> temperatures{node, "temperatures"};auto writer = makeAnyKeyWriter(temperatures, "temperature-writer");Publishing Samples
Writers are responsible for publishing data samples to a topic.
Single-Key Writer
A SingleKeyWriter provides the following methods for publishing samples:
- add — publishes an
Addsample. - update — publishes an
Updatesample. - remove — publishes a
Removesample (no value is included). - partialUpdate — returns a function that can be used to publish partial update samples for a given update tag.
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 samplewriter.add(21.0f);
// Publish an Update samplewriter.update(20.0f);
// Publish a PartialUpdate sample with the "increment" updaterauto increment = writer.partialUpdate<float>("increment");increment(0.5f);
// Publish a Remove sample. Remove samples don’t include a valuewriter.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.
Multi-Key and Any-Key Writers
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.
Topic<string, float> temperatures{node, "temperatures"};MultiKeyWriter<string, float> writer{ temperatures, {"floor1/kitchen", "floor1/living-room"}, "first-floor-writer"};
// Publish an Add samplewriter.add("floor1/kitchen", 21.0f);
// Publish an Update samplewriter.update("floor1/kitchen", 20.0f);
// Publish a PartialUpdate sample with the "increment" updaterauto increment = writer.partialUpdate<float>("increment");increment("floor1/kitchen", 0.5f);
// Publish a Remove samplewriter.remove("floor1/kitchen");Writer Configuration
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:
- Global defaults Using DataStorm.Topic.* properties (e.g.,
DataStorm.Topic.SampleCount) - Topic-level defaults By calling Topic::setWriterDefaultConfig
- Per-writer configuration Via the writer constructor or makeXxxWriter helper functions
Precedence: lower levels override higher ones (per-writer config > topic defaults > global properties). DataStorm takes each option you leave unset from the next level.
Options
Sample Count (sampleCount)
sampleCount)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.
Sample Lifetime (sampleLifetime)
sampleLifetime)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.
Clear History (clearHistory)
clearHistory)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 anAddsample.OnRemove: Clears the queue when publishing aRemovesample.OnAll: Clears the queue when publishing any sample.OnAllExceptPartialUpdate: Clears the queue when publishing any sample except aPartialUpdate.Never: Never clears the queue automatically.
Priority (priority)
priority)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.
Coordination & Listeners
Writers provide methods and listener callbacks to coordinate with connected readers.
Coordination Methods
- hasReaders — checks whether any readers are currently connected.
- waitForReaders — waits for the given number of readers to connect (default
1). - waitForNoReaders — blocks until all readers disconnect.
- getConnectedKeys — returns the set of keys for which at least one reader is connected.
- getConnectedReaders — returns the names of connected readers.
Connected Keys Listener
Use onConnectedKeys(initCallback, updateCallback) to register callbacks that monitor connected keys, replacing any callbacks registered before:
- DataStorm calls
initCallbackonce with the initial set of connected keys. - DataStorm calls
updateCallbackwhenever a key is connected or disconnected.
Connected Readers Listener
Use onConnectedReaders(initCallback, updateCallback) to register callbacks that monitor connected readers, replacing any callbacks registered before:
- DataStorm calls
initCallbackonce with the initial set of connected readers. - DataStorm calls
updateCallbackwhenever a reader connects or disconnects.