Skip to content
Start free evaluation

pdcomm_gem_configure_spooling

Function

Attaches an Equipment spool to a GEM endpoint.

PdcommStatus pdcomm_gem_configure_spooling(PdcommTcpEndpoint *endpoint, const PdcommGemSpoolOptions *options, const PdcommGemSpoolMessageKey *catalog, size_t count, const char *path, size_t path_length, PdcommGemSpoolWriteInfo *info)

Declared in: #include <pdcomm_gem_spooling.h>

Call once while the endpoint is stopped, after pdcomm_gem_configure_equipment(). With NULL and a zero path_length the spool lives in RAM. With a path, the spool is backed by a bounded snapshot file guarded by an exclusive lock on <path>.lock; the parent directory must already exist.

  • A new store (RAM or a file that does not exist yet) requires a nonempty, valid catalog and installs an initial disabled snapshot before attaching: spooling disabled, overflow #PDCOMM_GEM_SPOOL_DISCARD_NEW, unbounded transmit, empty selection. info then reports #PDCOMM_GEM_SPOOL_CONFIGURED.
  • An existing file is loaded with its persisted catalog, options, selection, queue, and statistics, and is not rewritten. A nonempty catalog must match the persisted catalog exactly, in order; NULL and a zero count accept the loaded catalog. An existing snapshot is never silently replaced or migrated, and a corrupt one is rejected.

If the initial snapshot was installed but the directory sync failed, the spool is attached anyway and the call returns #PDCOMM_SPOOL_UNCONFIRMED; do not configure again as if the installation had been rolled back.

Parameters

NameDescription
endpointStopped endpoint configured as GEM Equipment.
optionsStorage limits; version must be #PDCOMM_GEM_SPOOL_OPTIONS_VERSION and reserved 0.
catalogArray of count spoolable message keys. May be NULL when count is 0.
countNumber of catalog entries; at most options->max_catalog_entries.
pathUTF-8 snapshot path without a terminating NUL, or NULL for RAM. Embedded NUL bytes are rejected.
path_lengthLength of path in bytes; 0 selects RAM.
infoReceives the outcome of the initial snapshot. Must not be NULL; struct_size must be set.

Returns

#PDCOMM_OK on success (also when an existing file was loaded); #PDCOMM_SPOOL_UNCONFIRMED when the initial snapshot was installed without a confirmed directory sync; #PDCOMM_INVALID_ARGUMENT for a NULL or short info or options, a wrong version or reserved, NULL arrays with nonzero lengths, an invalid UTF-8 path or embedded NUL, a path without a file name or a max_serialized_bytes below 144 with a path, an empty catalog for a new store, an invalid or duplicate catalog key, or zero GEM item limits; #PDCOMM_INVALID_STATE when the endpoint is not stopped, is not GEM Equipment, or already has a spool; #PDCOMM_BACKPRESSURE when a staged TCP event is pending or the snapshot lock is held by another owner; #PDCOMM_LIMIT_EXCEEDED when the catalog exceeds its limit or the snapshot exceeds max_serialized_bytes; #PDCOMM_INVALID_DATA when the snapshot is corrupt or its catalog does not match catalog; #PDCOMM_IO_ERROR for file system errors; #PDCOMM_ALLOCATION_FAILED, #PDCOMM_POISONED, or #PDCOMM_INVALID_ARGUMENT for a NULL endpoint.

Notes

  • On failure nothing is attached and an existing file is unchanged.
  • The snapshot lock is held until the endpoint is destroyed.

Privacy Policy