Inheritance diagram for JEventSource:

Collaboration diagram for JEventSource:

Public Types
enum class	Result { Success , FailureTryAgain , FailureFinished , FailureLevelChange }
	Result describes what happened the last time a GetEvent() was attempted. More...

enum class	RETURN_STATUS { kSUCCESS , kNO_MORE_EVENTS , kBUSY , kTRY_AGAIN , kERROR , kUNKNOWN }
	The user is supposed to throw RETURN_STATUS::kNO_MORE_EVENTS or kBUSY from GetEvent()

Public Types inherited from jana::components::JComponent
enum class	Status { Uninitialized , Initialized , Opened , Closed , Finalized }

enum class	CallbackStyle { LegacyMode , ExpertMode , DeclarativeMode }

Public Member Functions
	JEventSource (std::string resource_name, JApplication *app=nullptr)

virtual void	Init ()

virtual void	Open ()
	`Open` is called by JANA when it is ready to accept events from this event source.

virtual Result	Emit (JEvent &)

virtual void	ProcessParallel (JEvent &) const
	For work that should be done in parallel on a JEvent, but is tightly coupled to the JEventSource for some reason.

virtual void	FinishEvent (JEvent &)
	`FinishEvent` is used to notify the `JEventSource` that an event has been completely processed.

virtual void	Close ()
	`Close` is called by JANA when it is finished accepting events from this event source.

virtual void	GetEvent (std::shared_ptr< JEvent >)
	`GetEvent` is called by JANA in order to emit a fresh event into the stream.

virtual bool	GetObjects (const std::shared_ptr< const JEvent > &, JFactory *)
	`GetObjects` was historically used for lazily unpacking data from a JEvent and putting it into a "dummy" JFactory.

virtual std::pair< JEventSource::Result, size_t >	Skip (JEvent &event, size_t events_to_skip)
	`Skip` allows the user to move forward in the file without having to read and discard entire events.

std::string	GetResourceName () const

uint64_t	GetEmittedEventCount () const

uint64_t	GetSkippedEventCount () const

uint64_t	GetProcessedEventCount () const

const std::vector< JEventLevel >	GetEventLevels ()

bool	IsGetObjectsEnabled () const

bool	IsFinishEventEnabled () const

bool	IsProcessParallelEnabled () const

uint64_t	GetNSkip ()

uint64_t	GetNEvents ()

virtual std::string	GetVDescription () const
	Optional for getting description via source rather than JEventSourceGenerator.

void	SetResourceName (std::string resource_name)

void	EnableFinishEvent (bool enable=true)
	EnableFinishEvent() is intended to be called by the user in the constructor in order to tell JANA to call the provided FinishEvent method after all JEventProcessors have finished with a given event.

void	EnableGetObjects (bool enable=true)

void	EnableProcessParallel (bool enable=true)

void	SetNEvents (uint64_t nevents)

void	SetNSkip (uint64_t nskip)

void	SetNextEventLevel (JEventLevel level)

void	SetEventLevels (std::vector< JEventLevel > levels)

JEventLevel	GetNextInputLevel () const

virtual void	DoInit ()

void	DoOpen (bool with_lock=true)

void	DoClose (bool with_lock=true)

Result	DoNext (std::shared_ptr< JEvent > event)

Result	DoNextCompatibility (std::shared_ptr< JEvent > event)

void	DoFinishEvent (JEvent &event)

void	Summarize (JComponentSummary &summary) const override

Public Member Functions inherited from jana::components::JComponent
void	SetLevel (JEventLevel level)

void	SetCallbackStyle (CallbackStyle style)

void	SetPrefix (std::string prefix)

void	SetTypeName (std::string type_name)
	For convenience, we provide a NAME_OF_THIS macro so that the user doesn't have to store the type name as a string, because that could get out of sync if automatic refactoring tools are used.

JApplication *	GetApplication () const

JLogger &	GetLogger ()

std::string	GetPrefix () const

JEventLevel	GetLevel () const

std::string	GetLoggerName () const

std::string	GetPluginName () const

void	SetLoggerName (std::string logger_name)

void	SetPluginName (std::string plugin_name)

std::string	GetTypeName () const

CallbackStyle	GetCallbackStyle () const

Status	GetStatus () const

void	SetApplication (JApplication *app)

void	SetLogger (JLogger logger)

template<typename F >
void	CallWithJExceptionWrapper (std::string func_name, F func)

void	RegisterParameter (ParameterBase *parameter)

void	RegisterService (ServiceBase *service)

const std::vector< ParameterBase * >	GetAllParameters () const

Public Member Functions inherited from jana::components::JHasOutputs
const std::vector< OutputBase * > &	GetOutputs () const

const std::vector< VariadicOutputBase * > &	GetVariadicOutputs () const

JDatabundle *	GetFirstDatabundle () const

void	RegisterOutput (OutputBase *output)

void	RegisterOutput (VariadicOutputBase *output)

void	SummarizeOutputs (JComponentSummary::Component &summary) const

void	WireOutputs (JEventLevel component_level, const std::vector< std::string > &single_output_databundle_names, const std::vector< std::vector< std::string > > &variadic_output_databundle_names, bool use_short_names)

Additional Inherited Members
Protected Attributes inherited from jana::components::JComponent
std::vector< ParameterBase * >	m_parameters

std::vector< ServiceBase * >	m_services

JEventLevel	m_level = JEventLevel::PhysicsEvent

CallbackStyle	m_callback_style = CallbackStyle::LegacyMode

std::string	m_prefix

std::string	m_plugin_name

std::string	m_logger_name

std::string	m_type_name

Status	m_status = Status::Uninitialized

std::mutex	m_mutex

JApplication *	m_app = nullptr

JLogger	m_logger

Member Enumeration Documentation

◆ Result

enum class JEventSource::Result

strong

Result describes what happened the last time a GetEvent() was attempted.

If Emit() or GetEvent() reaches an error state, it should throw a JException instead.

Member Function Documentation

◆ Close()

virtual void JEventSource::Close ( )

inlinevirtual

Close is called by JANA when it is finished accepting events from this event source.

Here is where you should cleanly close files, sockets, etc. Although GetEvent() knows when (for instance) there are no more events in a file, the logic for closing needs to live here because there are other ways a computation may end besides running out of events in a file. For instance, the user may want to process a limited number of events using the jana:nevents parameter, or they may want to terminate the computation manually using Ctrl-C.

◆ EnableFinishEvent()

void JEventSource::EnableFinishEvent ( bool enable = true )

inline

EnableFinishEvent() is intended to be called by the user in the constructor in order to tell JANA to call the provided FinishEvent method after all JEventProcessors have finished with a given event.

This should only be enabled when absolutely necessary (e.g. for backwards compatibility) because it introduces contention for the JEventSource mutex, which will hurt performance. Conceptually, FinishEvent isn't great, and so should be avoided when possible.

◆ FinishEvent()

virtual void JEventSource::FinishEvent ( JEvent & )

inlinevirtual

FinishEvent is used to notify the JEventSource that an event has been completely processed.

This is the final chance to interact with the JEvent before it is either cleared and recycled, or deleted. Although it is possible to use this for freeing JObjects stored in the JEvent , this is strongly discouraged in favor of putting that logic on the destructor, RAII-style. Instead, this callback should be used for updating and freeing state owned by the JEventSource, e.g. raw data which is keyed off of run number and therefore shared among multiple JEvents. FinishEvent is also well-suited for use with EventGroups, e.g. to notify someone that a batch of events has finished, or to implement "barrier events".

Referenced by Skip().

◆ GetEvent()

virtual void JEventSource::GetEvent ( std::shared_ptr< JEvent > )

inlinevirtual

GetEvent is called by JANA in order to emit a fresh event into the stream.

JANA manages the entire lifetime of the JEvent. The JEvent being passed in is empty and merely needs to hydrated as follows:

SetRunNumber()
SetEventNumber()
Insert<T>() raw data of type T into the JEvent container. Note that T should be a child class, such as FADC250DigiHit, not a parent class such as JObject or TObject. Also note that Insert transfers ownership of the data to that JEvent. If the data is shared among multiple JEvents, e.g. BOR data, use SetFactoryFlags(JFactory::NOT_OBJECT_OWNER) Note that JEvents are usually recycled. Although all reconstruction data is cleared before GetEvent is called, the constituent JFactories may retain some state, e.g. statistics, or calibration data keyed off of run number. If an event cannot be emitted, either because the resource is not ready or because we have reached the end of the event stream, the implementor should throw the corresponding RETURN_STATUS. The user should NEVER throw RETURN_STATUS SUCCESS because this will hurt performance. Instead, they should simply return normally.

Referenced by Skip().

◆ GetObjects()

virtual bool JEventSource::GetObjects	(	const std::shared_ptr< const JEvent > &	,
		JFactory *
	)

inlinevirtual

GetObjects was historically used for lazily unpacking data from a JEvent and putting it into a "dummy" JFactory.

This mechanism has been replaced by JEvent::Insert. All lazy evaluation should happen in a (non-dummy) JFactory, whereas eager evaluation should happen in JEventSource::GetEvent via JEvent::Insert.

◆ Open()

virtual void JEventSource::Open ( )

inlinevirtual

Open is called by JANA when it is ready to accept events from this event source.

The implementor should open file pointers or sockets here, instead of in the constructor. This is because the implementor won't know how many or which event sources the user will decide to activate within one job. Thus the implementor can avoid problems such as running out of file pointers, or multiple event sources attempting to bind to the same socket.

◆ ProcessParallel()

virtual void JEventSource::ProcessParallel ( JEvent & ) const

inlinevirtual

For work that should be done in parallel on a JEvent, but is tightly coupled to the JEventSource for some reason.

Called after Emit() by JEventMapArrow, but only if EnableProcessParallel(true) is set. Note that the JEvent& is not const here, because we need to be able to call event.Insert() from here. Also note that this IS const, because it is not safe to access any state in parallel from here. Note that this includes things like calibration constants. If you need to safely access state, put use a JFactory instead.

◆ Skip()

std::pair< JEventSource::Result, size_t > JEventSource::Skip	(	JEvent &	event,
		size_t	events_to_skip
	)

virtual

Skip allows the user to move forward in the file without having to read and discard entire events.

It takes as inputs an event object and the number of events to skip, and returns a pair containing a JEventSource::Result and the number of events that still need to be skipped. The event object can be completely ignored. If it is populated, however, it should be cleared before Skip() returns.

References FinishEvent(), and GetEvent().

◆ Summarize()

void JEventSource::Summarize ( JComponentSummary & summary ) const

overridevirtual

Reimplemented from jana::components::JComponent.

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

JEventSource.h
JEventSource.cc

Public Types

Public Member Functions

Additional Inherited Members

Member Enumeration Documentation

◆ Result

Member Function Documentation

◆ Close()

◆ EnableFinishEvent()

◆ FinishEvent()

◆ GetEvent()

◆ GetObjects()

◆ Open()

◆ ProcessParallel()

◆ Skip()

◆ Summarize()