Abstract base class for all gstreamer output plugins. More...

#include <gstreamer.h>

Public Member Functions
	GStreamer (const std::shared_ptr< GOptions > &g)
	Construct the streamer base and initialize module logging.

virtual	~GStreamer ()=default
	Virtual destructor.

virtual bool	openConnection ()
	Open the output medium used by this streamer.

bool	closeConnection ()
	Close the output medium after flushing buffered events.

virtual bool	closeConnectionImpl ()
	Plugin-specific close implementation hook.

void	publishEventData (const std::shared_ptr< GEventDataCollection > &event_data)
	Queue one event for publication.

void	publishRunData (const std::shared_ptr< GRunDataCollection > &run_data)
	Publish one run-level data collection immediately.

std::string	getStreamType () const
	Return the semantic stream type associated with this streamer instance.

void	define_gstreamer (const GStreamerDefinition &gstreamerDefinition, int tid=-1)
	Assign the output definition used by this streamer instance.

void	set_loggers (const std::shared_ptr< GOptions > &g)
	Load streamer runtime settings from the parsed options container.

Public Member Functions inherited from GBase< GStreamer >
	GBase (const std::shared_ptr< GOptions > &gopt, std::string logger_name="")

	GBase (const std::shared_ptr< GLogger > &logger)

	GBase (const GBase &)=default

	GBase (GBase &&) noexcept=default

virtual	~GBase ()

GBase &	operator= (const GBase &)=default

GBase &	operator= (GBase &&) noexcept=default

Static Public Member Functions
static const std::vector< std::string > &	supported_formats ()
	Return the list of output format tokens supported by the module.

static bool	is_valid_format (const std::string &format)
	Validate whether a format token is supported.

static GStreamer *	instantiate (const dlhandle h, std::shared_ptr< GOptions > g)
	Instantiate a streamer plugin from a dynamic library handle.

Protected Member Functions
bool	startEvent (const std::shared_ptr< GEventDataCollection > &event_data)
	Begin publishing one buffered event.

virtual bool	startEventImpl (const std::shared_ptr< GEventDataCollection > &event_data)
	Plugin-specific implementation hook called at the start of one event publish sequence.

bool	endEvent (const std::shared_ptr< GEventDataCollection > &event_data)
	End publishing one buffered event.

virtual bool	endEventImpl (const std::shared_ptr< GEventDataCollection > &event_data)
	Plugin-specific implementation hook called at the end of one event publish sequence.

bool	publishEventHeader (const std::unique_ptr< GEventHeader > &gevent_header)
	Publish the event header for the current event sequence.

virtual bool	publishEventHeaderImpl (const std::unique_ptr< GEventHeader > &gevent_header)
	Plugin-specific implementation hook for serializing one event header.

bool	publishEventTrueInfoData (const std::string &detectorName, const std::vector< const GTrueInfoData * > &trueInfoData)
	Publish the true-information hit bank for one detector.

virtual bool	publishEventTrueInfoDataImpl (const std::string &detectorName, const std::vector< const GTrueInfoData * > &trueInfoData)
	Plugin-specific implementation hook for one detector true-information collection.

bool	publishEventDigitizedData (const std::string &detectorName, const std::vector< const GDigitizedData * > &digitizedData)
	Publish the digitized hit bank for one detector.

virtual bool	publishEventDigitizedDataImpl (const std::string &detectorName, const std::vector< const GDigitizedData * > &digitizedData)
	Plugin-specific implementation hook for one detector digitized collection.

bool	startRun (const std::shared_ptr< GRunDataCollection > &run_data)
	Begin publishing one run-level collection.

virtual bool	startRunImpl (const std::shared_ptr< GRunDataCollection > &run_data)
	Plugin-specific implementation hook called at the start of a run publish sequence.

bool	endRun (const std::shared_ptr< GRunDataCollection > &run_data)
	End publishing one run-level collection.

virtual bool	endRunImpl (const std::shared_ptr< GRunDataCollection > &run_data)
	Plugin-specific implementation hook called at the end of a run publish sequence.

bool	publishRunHeader (const std::unique_ptr< GRunHeader > &run_header)
	Publish the run header for the current run sequence.

virtual bool	publishRunHeaderImpl (const std::unique_ptr< GRunHeader > &run_header)
	Plugin-specific implementation hook for serializing one run header.

bool	publishRunDigitizedData (const std::string &detectorName, const std::vector< const GDigitizedData * > &digitizedData)
	Publish run-level digitized data for one detector.

virtual bool	publishRunDigitizedDataImpl (const std::string &detectorName, const std::vector< const GDigitizedData * > &digitizedData)
	Plugin-specific implementation hook for one detector run-level digitized collection.

bool	startStream (const GFrameDataCollection *frameRunData)
	Begin publishing one frame stream record.

virtual bool	startStreamImpl (const GFrameDataCollection *frameRunData)
	Plugin-specific implementation hook called at the start of a frame stream record.

bool	publishFrameHeader (const GFrameHeader *gframeHeader)
	Publish one frame header.

virtual bool	publishFrameHeaderImpl (const GFrameHeader *gframeHeader)
	Plugin-specific implementation hook for serializing one frame header.

bool	publishPayload (const std::vector< GIntegralPayload * > *payload)
	Publish one frame payload.

virtual bool	publishPayloadImpl (const std::vector< GIntegralPayload * > *payload)
	Plugin-specific implementation hook for serializing one frame payload.

bool	endStream (const GFrameDataCollection *frameRunData)
	End publishing one frame stream record.

virtual bool	endStreamImpl (const GFrameDataCollection *frameRunData)
	Plugin-specific implementation hook called at the end of a frame stream record.

void	flushEventBuffer ()
	Flush all buffered events to the backend in publish order.

Protected Attributes
GStreamerDefinition	gstreamer_definitions
	Output definition currently bound to this streamer instance.

Protected Attributes inherited from GBase< GStreamer >
std::shared_ptr< GLogger >	log

Detailed Description

A concrete streamer is responsible for serializing GEMC data collections into a specific backend format. The base class centralizes the common workflow:

connection lifecycle management
event buffering
ordered publish sequences for event, run, and frame data
logger setup and configuration propagation

Concrete plugins override only the protected implementation hooks they support.

Lifecycle

A typical plugin instance follows this lifecycle:

construct the concrete streamer
bind one output definition through define_gstreamer()
load runtime settings through set_loggers()
call openConnection()
publish run, event, or frame data
call closeConnection()

For event-based output, publication is buffered. Events are accumulated in memory and written in batches when the configured buffer threshold is reached or when the connection is closed.

Buffering model

Event publication uses an internal buffer of std::shared_ptr<GEventDataCollection>. This design ensures that all event-owned objects remain alive for the full duration of a flush. During the flush, the base class extracts raw pointers from the detector collections and passes them to plugin hooks as read-only views.

The buffer is flushed when:

the number of queued events reaches bufferFlushLimit
closeConnection() is called
startStream() is called, to avoid mixing buffered event data with frame data

Threading expectations

The class itself does not perform external synchronization. The intended usage pattern is one streamer instance per worker thread. The helper gstreamersMapPtr() follows that model by creating a per-thread map of streamer objects.

Sharing one streamer instance across threads is only safe if the derived plugin implements its own synchronization policy.

Plugin factory symbol

Concrete plugins are loaded dynamically and must expose an extern "C" factory function named GStreamerFactory. The static helper instantiate() resolves that symbol from a dynamic library handle and constructs the plugin object.

Definition at line 76 of file gstreamer.h.

Constructor & Destructor Documentation

◆ GStreamer()

GStreamer::GStreamer ( const std::shared_ptr< GOptions > & g )

inlineexplicit

Parameters

g	Parsed options container used by the base logger infrastructure.

Definition at line 84 of file gstreamer.h.

◆ ~GStreamer()

virtual GStreamer::~GStreamer ( )

virtualdefault

A virtual destructor is required because streamer instances are manipulated through base-class pointers while the actual object type is a concrete plugin.

Member Function Documentation

◆ closeConnection()

bool GStreamer::closeConnection ( )

inline

This public wrapper guarantees that pending event data are published before the plugin-specific close logic executes.

Returns: true on success, false on failure.

Definition at line 113 of file gstreamer.h.

◆ closeConnectionImpl()

virtual bool GStreamer::closeConnectionImpl ( )

inlinevirtual

Concrete plugins override this to release backend resources after the common wrapper has already handled event-buffer flushing.

Returns: true on success, false on failure.

Definition at line 126 of file gstreamer.h.

◆ define_gstreamer()

void GStreamer::define_gstreamer	(	const GStreamerDefinition &	gstreamerDefinition,
		int	tid = -1 )

inline

The assigned definition determines the format token, base filename, type, and optional thread-specialized naming.

Parameters

gstreamerDefinition	Streamer definition to bind to this instance.
tid	Worker thread id used to specialize the filename. The default value keeps the original name unchanged.

Definition at line 169 of file gstreamer.h.

◆ endEvent()

bool GStreamer::endEvent ( const std::shared_ptr< GEventDataCollection > & event_data )

inlineprotected

Parameters

event_data Event collection being published.

Returns: true on success, false on failure.

Definition at line 243 of file gstreamer.h.

◆ endEventImpl()

virtual bool GStreamer::endEventImpl ( const std::shared_ptr< GEventDataCollection > & event_data )

inlineprotectedvirtual

Parameters

event_data Event collection being published.

Returns: true on success, false on failure.

Definition at line 254 of file gstreamer.h.

◆ endRun()

bool GStreamer::endRun ( const std::shared_ptr< GRunDataCollection > & run_data )

inlineprotected

Parameters

run_data Run collection being published.

Returns: true on success, false on failure.

Definition at line 371 of file gstreamer.h.

◆ endRunImpl()

virtual bool GStreamer::endRunImpl ( const std::shared_ptr< GRunDataCollection > & run_data )

inlineprotectedvirtual

Parameters

run_data Run collection being published.

Returns: true on success, false on failure.

Definition at line 382 of file gstreamer.h.

◆ endStream()

bool GStreamer::endStream ( const GFrameDataCollection * frameRunData )

inlineprotected

Parameters

frameRunData Frame collection being published.

Returns: true on success, false on failure.

Definition at line 499 of file gstreamer.h.

◆ endStreamImpl()

virtual bool GStreamer::endStreamImpl ( const GFrameDataCollection * frameRunData )

inlineprotectedvirtual

Parameters

frameRunData Frame collection being published.

Returns: true on success, false on failure.

Definition at line 510 of file gstreamer.h.

◆ flushEventBuffer()

void GStreamer::flushEventBuffer ( )

protected

For each buffered event, the base class executes the event publish sequence and then clears the internal buffer. This method is called automatically when buffering reaches its threshold, when the connection is closed, and before frame streaming begins.

Definition at line 73 of file gstreamer.cc.

◆ getStreamType()

std::string GStreamer::getStreamType ( ) const

inline

The type comes from the configured GStreamerDefinition and is typically "event" or "stream".

Returns: Stream type string stored in the current definition.

Definition at line 157 of file gstreamer.h.

◆ instantiate()

static GStreamer * GStreamer::instantiate	(	const dlhandle	h,
		std::shared_ptr< GOptions >	g )

inlinestatic

The method resolves the required GStreamerFactory symbol and invokes it with the supplied options object.

Parameters

h	Dynamic library handle.
g	Parsed options container forwarded to the plugin constructor.

Returns: Newly created plugin instance, or nullptr when the handle or symbol is invalid.

Definition at line 549 of file gstreamer.h.

◆ is_valid_format()

bool GStreamer::is_valid_format ( const std::string & format )

static

Validation is case-insensitive.

Parameters

format Format token to validate.

Returns: true when the token matches one of the supported formats, false otherwise.

Definition at line 17 of file gstreamer.cc.

◆ openConnection()

virtual bool GStreamer::openConnection ( )

inlinevirtual

Concrete plugins override this to acquire their backend resources, such as files, sockets, or format-specific handles.

Returns: true on success, false on failure.

Definition at line 103 of file gstreamer.h.

◆ publishEventData()

void GStreamer::publishEventData ( const std::shared_ptr< GEventDataCollection > & event_data )

The event is appended to the internal event buffer. Once the number of buffered events reaches bufferFlushLimit, the base class flushes the entire buffer by calling the event publish hook sequence on the derived plugin.

Parameters

event_data Event data collection to publish.

Definition at line 25 of file gstreamer.cc.

◆ publishEventDigitizedData()

bool GStreamer::publishEventDigitizedData	(	const std::string &	detectorName,
		const std::vector< const GDigitizedData * > &	digitizedData )

inlineprotected

The vector contains raw pointers into event-owned digitized hit objects and is valid for the duration of the flush.

Parameters

detectorName	Detector or sensitive-detector name identifying the collection.
digitizedData	Raw-pointer view of the detector digitized hits.

Returns: true on success, false on failure.

Definition at line 321 of file gstreamer.h.

◆ publishEventDigitizedDataImpl()

virtual bool GStreamer::publishEventDigitizedDataImpl	(	const std::string &	detectorName,
		const std::vector< const GDigitizedData * > &	digitizedData )

inlineprotectedvirtual

Parameters

detectorName	Detector or sensitive-detector name.
digitizedData	Raw-pointer view of the detector digitized hits.

Returns: true on success, false on failure.

Definition at line 334 of file gstreamer.h.

◆ publishEventHeader()

bool GStreamer::publishEventHeader ( const std::unique_ptr< GEventHeader > & gevent_header )

inlineprotected

The wrapper validates the header pointer, emits debug logging, and delegates serialization to the plugin implementation.

Parameters

gevent_header Unique pointer owned by the source event collection.

Returns: true on success, false on failure.

Definition at line 267 of file gstreamer.h.

◆ publishEventHeaderImpl()

virtual bool GStreamer::publishEventHeaderImpl ( const std::unique_ptr< GEventHeader > & gevent_header )

inlineprotectedvirtual

Parameters

gevent_header Unique pointer owned by the source event collection.

Returns: true on success, false on failure.

Definition at line 279 of file gstreamer.h.

◆ publishEventTrueInfoData()

bool GStreamer::publishEventTrueInfoData	(	const std::string &	detectorName,
		const std::vector< const GTrueInfoData * > &	trueInfoData )

inlineprotected

The vector contains raw pointers into event-owned hit objects. Those objects remain valid for the duration of the flush because the owning event remains stored in the internal buffer.

Parameters

detectorName	Detector or sensitive-detector name identifying the collection.
trueInfoData	Raw-pointer view of the detector true-information hits.

Returns: true on success, false on failure.

Definition at line 293 of file gstreamer.h.

◆ publishEventTrueInfoDataImpl()

virtual bool GStreamer::publishEventTrueInfoDataImpl	(	const std::string &	detectorName,
		const std::vector< const GTrueInfoData * > &	trueInfoData )

inlineprotectedvirtual

Parameters

detectorName	Detector or sensitive-detector name.
trueInfoData	Raw-pointer view of the detector true-information hits.

Returns: true on success, false on failure.

Definition at line 306 of file gstreamer.h.

◆ publishFrameHeader()

bool GStreamer::publishFrameHeader ( const GFrameHeader * gframeHeader )

inlineprotected

Parameters

gframeHeader Frame header pointer supplied by the caller.

Returns: true on success, false on failure.

Definition at line 461 of file gstreamer.h.

◆ publishFrameHeaderImpl()

virtual bool GStreamer::publishFrameHeaderImpl ( const GFrameHeader * gframeHeader )

inlineprotectedvirtual

Parameters

gframeHeader Frame header pointer supplied by the caller.

Returns: true on success, false on failure.

Definition at line 472 of file gstreamer.h.

◆ publishPayload()

bool GStreamer::publishPayload ( const std::vector< GIntegralPayload * > * payload )

inlineprotected

Parameters

payload Pointer to the frame integral-payload vector.

Returns: true on success, false on failure.

Definition at line 480 of file gstreamer.h.

◆ publishPayloadImpl()

virtual bool GStreamer::publishPayloadImpl ( const std::vector< GIntegralPayload * > * payload )

inlineprotectedvirtual

Parameters

payload Pointer to the frame integral-payload vector.

Returns: true on success, false on failure.

Definition at line 491 of file gstreamer.h.

◆ publishRunData()

void GStreamer::publishRunData ( const std::shared_ptr< GRunDataCollection > & run_data )

Run data are not buffered. The base class dispatches the run publish sequence directly to the plugin-specific hooks.

Parameters

run_data Run data collection to publish.

Definition at line 45 of file gstreamer.cc.

◆ publishRunDigitizedData()

bool GStreamer::publishRunDigitizedData	(	const std::string &	detectorName,
		const std::vector< const GDigitizedData * > &	digitizedData )

inlineprotected

Parameters

detectorName	Detector or sensitive-detector name identifying the collection.
digitizedData	Raw-pointer view of the detector digitized data.

Returns: true on success, false on failure.

Definition at line 414 of file gstreamer.h.

◆ publishRunDigitizedDataImpl()

virtual bool GStreamer::publishRunDigitizedDataImpl	(	const std::string &	detectorName,
		const std::vector< const GDigitizedData * > &	digitizedData )

inlineprotectedvirtual

Parameters

detectorName	Detector or sensitive-detector name.
digitizedData	Raw-pointer view of the detector digitized data.

Returns: true on success, false on failure.

Definition at line 427 of file gstreamer.h.

◆ publishRunHeader()

bool GStreamer::publishRunHeader ( const std::unique_ptr< GRunHeader > & run_header )

inlineprotected

Parameters

run_header Unique pointer owned by the source run collection.

Returns: true on success, false on failure.

Definition at line 392 of file gstreamer.h.

◆ publishRunHeaderImpl()

virtual bool GStreamer::publishRunHeaderImpl ( const std::unique_ptr< GRunHeader > & run_header )

inlineprotectedvirtual

Parameters

run_header Unique pointer owned by the source run collection.

Returns: true on success, false on failure.

Definition at line 403 of file gstreamer.h.

◆ set_loggers()

void GStreamer::set_loggers ( const std::shared_ptr< GOptions > & g )

inline

At present this method configures the event buffer flush limit from the ebuffer option.

Parameters

g	Parsed options container supplying module configuration.

Definition at line 200 of file gstreamer.h.

◆ startEvent()

bool GStreamer::startEvent ( const std::shared_ptr< GEventDataCollection > & event_data )

inlineprotected

The wrapper validates the input event and its header, emits debug logging, and delegates the actual backend-specific behavior to the derived implementation.

Parameters

event_data Event collection being published.

Returns: true on success, false on failure.

Definition at line 217 of file gstreamer.h.

◆ startEventImpl()

virtual bool GStreamer::startEventImpl ( const std::shared_ptr< GEventDataCollection > & event_data )

inlineprotectedvirtual

Parameters

event_data Event collection being published.

Returns: true on success, false on failure.

Definition at line 233 of file gstreamer.h.

◆ startRun()

bool GStreamer::startRun ( const std::shared_ptr< GRunDataCollection > & run_data )

inlineprotected

Parameters

run_data Run collection being published.

Returns: true on success, false on failure.

Definition at line 345 of file gstreamer.h.

◆ startRunImpl()

virtual bool GStreamer::startRunImpl ( const std::shared_ptr< GRunDataCollection > & run_data )

inlineprotectedvirtual

Parameters

run_data Run collection being published.

Returns: true on success, false on failure.

Definition at line 361 of file gstreamer.h.

◆ startStream()

bool GStreamer::startStream ( const GFrameDataCollection * frameRunData )

inlineprotected

Pending event data are flushed first so the output sequence remains well defined if a plugin supports both event and frame publication modes.

Parameters

frameRunData Frame collection being published.

Returns: true on success, false on failure.

Definition at line 441 of file gstreamer.h.

◆ startStreamImpl()

virtual bool GStreamer::startStreamImpl ( const GFrameDataCollection * frameRunData )

inlineprotectedvirtual

Parameters

frameRunData Frame collection being published.

Returns: true on success, false on failure.

Definition at line 453 of file gstreamer.h.

◆ supported_formats()

const std::vector< std::string > & GStreamer::supported_formats ( )

static

This list represents the built-in plugin formats recognized by the module-level validation helpers and option help text.

Returns: Reference to the static supported-format list.

Definition at line 11 of file gstreamer.cc.

Field Documentation

◆ gstreamer_definitions

GStreamerDefinition GStreamer::gstreamer_definitions

protected

Definition at line 206 of file gstreamer.h.

The documentation for this class was generated from the following files:

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Lifecycle

Buffering model

Threading expectations

Plugin factory symbol

Constructor & Destructor Documentation

◆ GStreamer()

◆ ~GStreamer()

Member Function Documentation

◆ closeConnection()

◆ closeConnectionImpl()

◆ define_gstreamer()

◆ endEvent()

◆ endEventImpl()

◆ endRun()

◆ endRunImpl()

◆ endStream()

◆ endStreamImpl()

◆ flushEventBuffer()

◆ getStreamType()

◆ instantiate()

◆ is_valid_format()

◆ openConnection()

◆ publishEventData()

◆ publishEventDigitizedData()

◆ publishEventDigitizedDataImpl()

◆ publishEventHeader()

◆ publishEventHeaderImpl()

◆ publishEventTrueInfoData()

◆ publishEventTrueInfoDataImpl()

◆ publishFrameHeader()

◆ publishFrameHeaderImpl()

◆ publishPayload()

◆ publishPayloadImpl()

◆ publishRunData()

◆ publishRunDigitizedData()

◆ publishRunDigitizedDataImpl()

◆ publishRunHeader()

◆ publishRunHeaderImpl()

◆ set_loggers()

◆ startEvent()

◆ startEventImpl()

◆ startRun()

◆ startRunImpl()

◆ startStream()

◆ startStreamImpl()

◆ supported_formats()

Field Documentation

◆ gstreamer_definitions