Writer

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, or keys) will attach so they can receive samples from that writer.

You can optionally assign a name to a writer at creation time. This name is visible to readers and is used in listener notifications (for connected writers or keys).

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

// Constructor
Topic<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

// Constructor
Topic<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 set
Topic<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 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.

Topic<string, float> temperatures{node, "temperatures"};
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 Remove sample. Remove samples don’t include a value
writer.remove();

Multi-Key and Any-Key Writers

The MultiKeyWriter—used for both multi-key and any-key writers—provides the same four methods, but they take an additional key parameter.

• 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 sample
writer.add("floor1/kitchen", 21.0f);

// Publish an Update sample
writer.update("floor1/kitchen", 20.0f);

// Publish a Remove sample
writer.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).

Options

Sample Count (sampleCount)

Specifies how many samples are kept in the writer’s history queue. When the queue is full, the oldest samples are discarded. Default: keep all samples.

Sample Lifetime (sampleLifetime)

Specifies how long samples are retained in the writer’s queue. Samples older than this duration are automatically removed.

Clear History (clearHistory)

Controls when the writer’s sample queue is cleared, based on sample events (ClearHistoryPolicy):

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

Priority (priority)

Specifies the priority of the writer. Readers can be configured with a discard policy (see DiscardPolicy::Priority) to only accept samples from the writer with the highest priority among those connected to the same topic.

Coordination & Listeners

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

Coordination Methods

• hasReaders — checks whether any readers are currently connected.

• waitForReaders — wait for readers to connect.

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

• The initCallbackis called immediately after registration with the initial set of connected keys.

• The updateCallbackis called whenever a key is connected or disconnected.

Connected Readers Listener

Use onConnectedReaders(initCallback, updateCallback) to register callbacks that monitor connected readers.

• The initCallback is called immediately after registration with the initial set of connected readers.

• The updateCallback is called whenever a reader connects or disconnects.