Abstract base class for streaming GEMC event or frame data to output media. More...

#include <gstreamer.h>

Public Member Functions
	GStreamer (const std::shared_ptr< GOptions > &g)
	Construct a streamer and bind it to module logging.

virtual	~GStreamer ()=default
	Virtual destructor.

virtual bool	openConnection ()
	Open the output medium (file, socket, etc.).

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

virtual bool	closeConnectionImpl ()
	Implementation hook for closing the output medium.

void	publishEventData (const std::shared_ptr< GEventDataCollection > &event_data)
	Buffer an event for later serialization.

std::string	getStreamType () const
	Return the semantic stream type for this streamer.

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)
	Configure streamer settings derived from options.

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 supported output formats.

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

static GStreamer *	instantiate (const dlhandle h, std::shared_ptr< GOptions > g)
	Instantiate a streamer plugin by resolving the `GStreamerFactory` symbol from a dynamic library.

Protected Member Functions
bool	startEvent (const std::shared_ptr< GEventDataCollection > &event_data)
	Begin an event publish sequence.

virtual bool	startEventImpl (const std::shared_ptr< GEventDataCollection > &event_data)
	Implementation hook for beginning an event publish sequence.

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

virtual bool	publishEventHeaderImpl (const std::unique_ptr< GEventHeader > &gevent_header)
	Implementation hook for publishing the event header.

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

virtual bool	publishEventTrueInfoDataImpl (const std::string &detectorName, const std::vector< const GTrueInfoData * > &trueInfoData)
	Implementation hook for publishing true info hits for one detector.

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

virtual bool	publishEventDigitizedDataImpl (const std::string &detectorName, const std::vector< const GDigitizedData * > &digitizedData)
	Implementation hook for publishing digitized hits for one detector.

bool	endEvent (const std::shared_ptr< GEventDataCollection > &event_data)
	End an event publish sequence.

virtual bool	endEventImpl (const std::shared_ptr< GEventDataCollection > &event_data)
	Implementation hook for ending an event publish sequence.

bool	startStream (const GFrameDataCollection *frameRunData)
	Begin a frame stream publish sequence.

virtual bool	startStreamImpl (const GFrameDataCollection *frameRunData)
	Implementation hook for beginning a frame stream publish sequence.

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

virtual bool	publishFrameHeaderImpl (const GFrameHeader *gframeHeader)
	Implementation hook for publishing a frame header.

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

virtual bool	publishPayloadImpl (const std::vector< GIntegralPayload * > *payload)
	Implementation hook for publishing a frame payload.

bool	endStream (const GFrameDataCollection *frameRunData)
	End a frame stream publish sequence.

virtual bool	endStreamImpl (const GFrameDataCollection *frameRunData)
	Implementation hook for ending a frame stream publish sequence.

void	flushEventBuffer ()
	Flush the internal event buffer, writing all buffered events to the output medium.

Protected Attributes
GStreamerDefinition	gstreamer_definitions
	Output definition used by this streamer (format, base name, type, thread id).

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

Detailed Description

Lifecycle

A typical usage sequence for a concrete streamer is:

Construct a derived streamer (usually through plugin loading).
Configure it by calling define_gstreamer() and set_loggers().
Open the underlying output medium via openConnection().
Publish data:
- Events: call publishEventData() for each event. Events are buffered and written out when the buffer reaches a configured limit, or when closeConnection() is invoked.
- Frames: frame streaming hooks exist, but frame publishing is currently plugin-defined (the base class provides the protected hook sequence).
Close the output medium via closeConnection().

Buffering model

The base class stores a per-streamer in-memory buffer of std::shared_ptr<GEventDataCollection>. The buffer is flushed by flushEventBuffer() when:

the number of buffered events reaches bufferFlushLimit, or
closeConnection() is called, or
startStream() is called (to avoid mixing event and frame streams).

During flushing, each event is treated as read-only: the base class extracts raw pointers from hit containers and passes those raw pointers to plugin hooks. The raw pointers remain valid for the duration of the flush because the owning event shared pointer is kept alive by the buffer.

Threading expectations

The gstreamer module is typically used with one streamer instance per worker thread. The helper gstreamer::gstreamersMapPtr() creates such per-thread streamer maps. The base class itself does not provide external synchronization; therefore:

Do not share a single streamer instance across multiple threads unless the derived class implements its own locking.

Plugin factory symbol

Streamer plugins are loaded through a dynamic loader. Each plugin must expose an extern "C" function named GStreamerFactory that returns a new GStreamer instance. The helper instantiate() resolves that symbol via dlsym.

Definition at line 65 of file gstreamer.h.

Constructor & Destructor Documentation

◆ GStreamer()

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

inlineexplicit

Parameters

g	Options container used to initialize logging and configuration.

Definition at line 72 of file gstreamer.h.

◆ ~GStreamer()

virtual GStreamer::~GStreamer ( )

virtualdefault

The destructor is virtual to ensure derived destructors run correctly when deleting through a base pointer.

Member Function Documentation

◆ closeConnection()

bool GStreamer::closeConnection ( )

inline

This calls flushEventBuffer() first, then delegates to closeConnectionImpl().

Returns: true on success, false on failure.

Definition at line 99 of file gstreamer.h.

◆ closeConnectionImpl()

virtual bool GStreamer::closeConnectionImpl ( )

inlinevirtual

Derived classes override this to release resources (close files, detach trees, etc.).

Returns: true on success, false on failure.

Definition at line 110 of file gstreamer.h.

◆ define_gstreamer()

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

inline

The caller may specify a thread id to specialize the filename. A negative thread id keeps the original base filename unchanged.

Parameters

gstreamerDefinition	Output definition (format, base filename, type).
tid	Thread id used to specialize the filename (defaults to -1, meaning "no specialization").

Definition at line 142 of file gstreamer.h.

◆ endEvent()

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

inlineprotected

Parameters

event_data Event being published.

Returns: true on success, false on failure.

Definition at line 292 of file gstreamer.h.

◆ endEventImpl()

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

inlineprotectedvirtual

Parameters

event_data Event being published.

Returns: true on success, false on failure.

Definition at line 302 of file gstreamer.h.

◆ endStream()

bool GStreamer::endStream ( const GFrameDataCollection * frameRunData )

inlineprotected

Parameters

frameRunData Frame container being published.

Returns: true on success, false on failure.

Definition at line 371 of file gstreamer.h.

◆ endStreamImpl()

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

inlineprotectedvirtual

Parameters

frameRunData Frame container being published.

Returns: true on success, false on failure.

Definition at line 381 of file gstreamer.h.

◆ flushEventBuffer()

void GStreamer::flushEventBuffer ( )

protected

The flush sequence is:

startEvent()
publishEventHeader()
publishEventTrueInfoData() for each detector collection
publishEventDigitizedData() for each detector collection
endEvent()

After flushing, the buffer is cleared.

Definition at line 34 of file gstreamer.cc.

◆ getStreamType()

std::string GStreamer::getStreamType ( ) const

inline

This value comes from gstreamer_definitions and is typically configured via options.

Returns: The type string (e.g. "event" or "stream").

Definition at line 131 of file gstreamer.h.

◆ instantiate()

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

inlinestatic

Parameters

h	Dynamic library handle.
g	Options container passed to the plugin constructor.

Returns: A new streamer instance, or nullptr if the handle or symbol is invalid.

Definition at line 422 of file gstreamer.h.

◆ is_valid_format()

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

static

Parameters

format Format token to validate (case-insensitive).

Returns: true if the format is supported, false otherwise.

Definition at line 14 of file gstreamer.cc.

◆ openConnection()

virtual bool GStreamer::openConnection ( )

inlinevirtual

Derived classes override this to acquire resources and validate accessibility.

Returns: true on success, false on failure.

Definition at line 89 of file gstreamer.h.

◆ publishEventData()

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

The event is appended to an internal buffer. When the buffer reaches the configured limit (bufferFlushLimit), the streamer flushes all buffered events in a single pass.

Parameters

event_data Event container to publish.

Definition at line 22 of file gstreamer.cc.

◆ publishEventDigitizedData()

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

inlineprotected

The digitizedData vector contains raw pointers that remain valid during the flush because the owning hit containers are owned by the buffered event.

Parameters

detectorName	Detector / sensitive detector name (map key in the event collection).
digitizedData	Raw pointers to digitized hits. The vector index corresponds to hit index.

Returns: true on success, false on failure.

Definition at line 269 of file gstreamer.h.

◆ publishEventDigitizedDataImpl()

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

inlineprotectedvirtual

Parameters

detectorName	Detector / sensitive detector name.
digitizedData	Raw pointers to digitized hits.

Returns: true on success, false on failure.

Definition at line 282 of file gstreamer.h.

◆ publishEventHeader()

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

inlineprotected

This wrapper validates gevent_header, logs a debug trace, then calls publishEventHeaderImpl().

Parameters

gevent_header Event header unique pointer owned by the event container.

Returns: true on success, false on failure.

Definition at line 215 of file gstreamer.h.

◆ publishEventHeaderImpl()

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

inlineprotectedvirtual

Parameters

gevent_header Event header unique pointer owned by the event container.

Returns: true on success, false on failure.

Definition at line 226 of file gstreamer.h.

◆ publishEventTrueInfoData()

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

inlineprotected

The trueInfoData vector contains raw pointers that remain valid during the flush because the owning hit containers are owned by the buffered event.

Parameters

detectorName	Detector / sensitive detector name (map key in the event collection).
trueInfoData	Raw pointers to true info hits. The vector index corresponds to hit index.

Returns: true on success, false on failure.

Definition at line 240 of file gstreamer.h.

◆ publishEventTrueInfoDataImpl()

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

inlineprotectedvirtual

Parameters

detectorName	Detector / sensitive detector name.
trueInfoData	Raw pointers to true info hits.

Returns: true on success, false on failure.

Definition at line 253 of file gstreamer.h.

◆ publishFrameHeader()

bool GStreamer::publishFrameHeader ( const GFrameHeader * gframeHeader )

inlineprotected

Parameters

gframeHeader Frame header pointer.

Returns: true on success, false on failure.

Definition at line 337 of file gstreamer.h.

◆ publishFrameHeaderImpl()

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

inlineprotectedvirtual

Parameters

gframeHeader Frame header pointer.

Returns: true on success, false on failure.

Definition at line 347 of file gstreamer.h.

◆ publishPayload()

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

inlineprotected

Parameters

payload Pointer to payload vector.

Returns: true on success, false on failure.

Definition at line 354 of file gstreamer.h.

◆ publishPayloadImpl()

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

inlineprotectedvirtual

Parameters

payload Pointer to payload vector.

Returns: true on success, false on failure.

Definition at line 364 of file gstreamer.h.

◆ set_loggers()

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

inline

Currently this extracts ebuffer and sets bufferFlushLimit.

Parameters

g	Options container.

Definition at line 167 of file gstreamer.h.

◆ startEvent()

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

inlineprotected

This wrapper validates event_data and its header, logs a debug trace, then calls startEventImpl().

Parameters

event_data Event being published.

Returns: true on success, false on failure.

Definition at line 187 of file gstreamer.h.

◆ startEventImpl()

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

inlineprotectedvirtual

Parameters

event_data Event being published.

Returns: true on success, false on failure.

Definition at line 202 of file gstreamer.h.

◆ startStream()

bool GStreamer::startStream ( const GFrameDataCollection * frameRunData )

inlineprotected

This wrapper flushes pending events (to avoid mixing event and frame streams), logs a debug trace, then calls startStreamImpl().

Parameters

frameRunData Frame container being published.

Returns: true on success, false on failure.

Definition at line 319 of file gstreamer.h.

◆ startStreamImpl()

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

inlineprotectedvirtual

Parameters

frameRunData Frame container being published.

Returns: true on success, false on failure.

Definition at line 330 of file gstreamer.h.

◆ supported_formats()

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

static

This is a function-local static instead of a global variable to avoid static destruction order issues.

Returns: Reference to a stable list of supported format tokens.

Definition at line 8 of file gstreamer.cc.

Field Documentation

◆ gstreamer_definitions

GStreamerDefinition GStreamer::gstreamer_definitions

protected

Definition at line 173 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()

◆ endStream()

◆ endStreamImpl()

◆ flushEventBuffer()

◆ getStreamType()

◆ instantiate()

◆ is_valid_format()

◆ openConnection()

◆ publishEventData()

◆ publishEventDigitizedData()

◆ publishEventDigitizedDataImpl()

◆ publishEventHeader()

◆ publishEventHeaderImpl()

◆ publishEventTrueInfoData()

◆ publishEventTrueInfoDataImpl()

◆ publishFrameHeader()

◆ publishFrameHeaderImpl()

◆ publishPayload()

◆ publishPayloadImpl()

◆ set_loggers()

◆ startEvent()

◆ startEventImpl()

◆ startStream()

◆ startStreamImpl()

◆ supported_formats()

Field Documentation

◆ gstreamer_definitions