Struct SolidSyslogStream¶

#include <SolidSyslogStreamDefinition.h>

struct SolidSyslogStream
{
    bool (*Open)(struct SolidSyslogStream* base, const struct SolidSyslogAddress* addr);
    bool (*Send)(struct SolidSyslogStream* base, const void* buffer, size_t size);
    SolidSyslogSsize (*Read)(struct SolidSyslogStream* base, void* buffer, size_t size);
    void (*Close)(struct SolidSyslogStream* base);
    uint32_t (*Version)(struct SolidSyslogStream* base);
};

Detailed Description¶

The contract a byte-stream transport (TCP, TLS over TCP) fills in; the library drives it from the servicing pass, so it need not be reentrant.

What a caller may expect of each call is documented on the corresponding SolidSyslogStream_* function in SolidSyslogStream.h; what follows is the same contract as obligations on the implementer.

Public Attributes Documentation¶

Close¶

Idempotent, and leaves the instance reusable - a later Open reconnects it.

void(* SolidSyslogStream::Close) (struct SolidSyslogStream *base);

Called on a stream that is already closed, on one that never opened, and again from Destroy.

Open¶

Bound the connect, and any handshake above it.

bool(* SolidSyslogStream::Open) (struct SolidSyslogStream *base, const struct SolidSyslogAddress *addr);

One servicing pass drives every sender, so a connect that blocks stalls the whole drain, not just this stream. Leave nothing open on a failed path: the caller retries with a bare Open and never calls Close first.

Read¶

Return 0 when nothing is available, never a negative - the two are acted on differently, and a would-block reported as an error costs a reconnect on an idle link.

SolidSyslogSsize(* SolidSyslogStream::Read) (struct SolidSyslogStream *base, void *buffer, size_t size);

Reserve the negative return for a real teardown, and close internally before making it.

Send¶

All-or-nothing.

bool(* SolidSyslogStream::Send) (struct SolidSyslogStream *base, const void *buffer, size_t size);

Never report a partial write as success - the record is gone from the caller's hands once you return true. If the whole buffer cannot go, close internally and return false; the caller reopens and store-and-forward replays.

A peer that has closed its end is the case to watch: a transport that stays writable after one will take a record nothing can deliver, and returning true there loses it. Establish that the connection is still whole, however your stack says so, before you accept the record.

Version¶

Report a monotonic version of this stream's own configuration - what it will present or accept on the next Open.

uint32_t(* SolidSyslogStream::Version) (struct SolidSyslogStream *base);

Bump it when that changes and the sender reconnects on its next pass. Polled every Send, so it must be cheap and pure. Make the change before moving the version: the sender may reconnect on the very next record, and a version moved first lets it reopen with the configuration being replaced. A stream with nothing to change reports 0 for its lifetime.

The documentation for this class was generated from the following file Core/Interface/SolidSyslogStreamDefinition.h