Syntalos::AbstractModule

Syntalos::AbstractModule

Abstract base class for all modules. More…

#include <moduleapi.h>

Inherits from QObject

Inherited by Syntalos::MLinkModule

Public Signals

Public Functions

Protected Functions

Protected Attributes

Friends

Detailed Description

class Syntalos::AbstractModule;

Abstract base class for all modules.

This class describes the interface for every Syntalos module and contains helper functions and other API to make writing modules simple.

Public Signals Documentation

signal actionsUpdated

void actionsUpdated()

signal stateChanged

void stateChanged(
    ModuleState state
)

signal error

void error(
    const QString & message
)

signal statusMessage

void statusMessage(
    const QString & message
)

signal nameChanged

void nameChanged(
    const QString & name
)

signal portsConnected

void portsConnected(
    const VarStreamInputPort * inPort,
    const StreamOutputPort * outPort
)

signal portConfigurationUpdated

void portConfigurationUpdated()

signal synchronizerDetailsChanged

void synchronizerDetailsChanged(
    const QString & id,
    const Syntalos::TimeSyncStrategies & strategies,
    const Syntalos::microseconds_t & tolerance
)

signal synchronizerOffsetChanged

void synchronizerOffsetChanged(
    const QString & id,
    const Syntalos::microseconds_t & currentOffset
)

Public Functions Documentation

function AbstractModule

explicit AbstractModule(
    QObject * parent =nullptr
)

function AbstractModule

explicit AbstractModule(
    const QString & id,
    QObject * parent =nullptr
)

function ~AbstractModule

virtual ~AbstractModule()

function state

ModuleState state() const

function setStateDormant

void setStateDormant()

Allow a running module to mark itself as idle.

This may be useful in case the module us missing an essential stream connection and essentially does nothing in a run.

function setStateReady

void setStateReady()

Allow a preparing module to mark itself as ready.

When a module is done preparing itself, e.g. by setting up its thread, it can switch to its ready state on its own and thereby allow the engine to start it. Usually doing this explicitly is not necessary.

function id

QString id() const

Name of this module used internally as unique identifier.

function index

int index() const

Index of this module.

The index is usually the count of modules of the same kind. E.g. the first “camera” module may have an index of 1, the second of 2, etc.

function name

virtual QString name() const

Name of this module displayed to the user.

function setName

virtual void setName(
    const QString & name
)

function driver

virtual ModuleDriverKind driver() const

Select how this module will be executed by the Syntalos engine.

Reimplemented by: Syntalos::MLinkModule::driver

function features

virtual ModuleFeatures features() const

Return a bitfield of features this module supports.

Reimplemented by: Syntalos::MLinkModule::features

function registerOutputPort

template <typename T >
inline requires std::is_base_of_v< BaseDataType, T > std::shared_ptr< DataStream< T > > registerOutputPort(
    const QString & id,
    const QString & title =QString()
)

Register an output port for this module.

Return: The data stream instance for this module to write to.

This function should be called in the module’s constructor to publish the intent to produce an output stream of type T. Other modules may subscribe to this stream.

function registerInputPort

template <typename T >
inline requires std::is_base_of_v< BaseDataType, T > std::shared_ptr< StreamInputPort< T > > registerInputPort(
    const QString & id,
    const QString & title =QString()
)

Register an input port for this module.

Return: A StreamInputPort instance, which can be checked for subscriptions

This function should be called in the module’s constructor to publish the intent to accept input stream subscriptions of type T. The user may subscribe this module to other modules which produce the data it accepts.

function registerOutputPortByTypeId

inline std::shared_ptr< VariantDataStream > registerOutputPortByTypeId(
    int typeId,
    const QString & id,
    const QString & title =QString()
)

Register an output port for this module using a type ID.

Return: A variant data stream instance for this module to write to.

This function permits registering an output port for a particular type when only knowing its type ID. This is usefuly when dynamically allocating ports.

function registerInputPortByTypeId

inline std::shared_ptr< VarStreamInputPort > registerInputPortByTypeId(
    int typeId,
    const QString & id,
    const QString & title =QString()
)

Register an input port for this module using a type ID.

Return: A VarStreamInputPort instance, which can be checked for subscriptions

function initialize

virtual bool initialize()

Initialize the module.

Return: true if success

Initialize this module. This method is called once after construction, and can be used to initialize parts of the module that may fail and may need to emit an error message (unlike in the constructor, which always succeeds)

function prepare

virtual bool prepare(
    const TestSubject & testSubject
) =0

Prepare for an experiment run.

Return: true if success

Reimplemented by: Syntalos::MLinkModule::prepare

Prepare this module to run. This method is called once prior to every experiment run.

function start

virtual void start()

Run when the experiment is started and the HRTimer has an initial time set. Switches the module into “Started” mode.

Reimplemented by: Syntalos::MLinkModule::start

function runThread

virtual void runThread(
    OptionalWaitCondition * startWaitCondition
)

Run task in a thread.

Return: true if no error

If the module advertises itself has being threaded, this function is executed in a new thread after the module has left its PREPARE stage. The module should only start to handle input when all modules are ready. This is the case when either the start() method was called, a start event was sent via the system status event stream or the wait condition unblocks (call waitCondition->wait(this) to wait for the start signal).

function processUiEvents

virtual void processUiEvents()

Called to process UI events.

If ModuleFeature::CALL_UI_EVENTS is set, the engine will explicitly call this method in quick succession to process UI events. Usually modules can hook into the main UI event loop using a QTimer at interval 0, but the added overhead of this method may be significant for modules which have to draw a lot of things on screen in quick succession. These modules may opt to implement this modules and set the CALL_UI_EVENTS feature for more efficient continuous drawing callbacks.

function stop

virtual void stop()

Stop running an experiment. Stop execution of an experiment. This method is called after prepare() was run.

Reimplemented by: Syntalos::MLinkModule::stop

function finalize

virtual void finalize()

Finalize this module. This method is called before the module itself is destroyed.

function showDisplayUi

virtual void showDisplayUi()

Show the display widgets of this module.

Reimplemented by: Syntalos::MLinkModule::showDisplayUi

function isDisplayUiVisible

virtual bool isDisplayUiVisible()

function showSettingsUi

virtual void showSettingsUi()

Show the configuration UI of this module.

Reimplemented by: Syntalos::MLinkModule::showSettingsUi

function isSettingsUiVisible

virtual bool isSettingsUiVisible()

function hideDisplayUi

virtual void hideDisplayUi()

Hide all display widgets of this module.

function hideSettingsUi

virtual void hideSettingsUi()

Hide the configuration UI of this module.

function actions

virtual QList< QAction * > actions()

Get actions to add to the module’s submenu.

Return:

function serializeSettings

virtual void serializeSettings(
    const QString & confBaseDir,
    QVariantHash & settings,
    QByteArray & extraData
)

Serialize the settings of this module.

Modules can add their settings keys and values to the Variant hashtable, and also can store arbitrary data as a byte array if they so choose.

function loadSettings

virtual bool loadSettings(
    const QString & confBaseDir,
    const QVariantHash & settings,
    const QByteArray & extraData
)

Load settings from previously stored data.

Return: true if successful.

See serializeSettings() for details. This method should act in reverse and restore settings from previously saved data.

function inputPortConnected

virtual void inputPortConnected(
    VarStreamInputPort * inPort
)

Called when one of this module’s input ports is subscribed to a stream.

function updateStartWaitCondition

virtual void updateStartWaitCondition(
    OptionalWaitCondition * waitCondition
)

Update thread start wait condition before each run.

This is a convenience funtion to provide modules which roll their own threads with a start-wait-condition just like Syntalos-managed threads have. The condition is only valid for the current run, and invalid afterwards!

function lastError

QString lastError() const

Return last error.

Return: The last error message generated by this module

function moduleRootDir

QString moduleRootDir() const

Obtain the root directory of this (loadable) module.

Return: Directory of this module as absolute path.

function setEventsMaxModulesPerThread

void setEventsMaxModulesPerThread(
    int maxModuleCount
)

Set maximum modules per thread when using dedicated event driver.

When this module’s driver is ModuleDriverKind::EVENTS_DEDICATED, the module can set a maximum amount of its instances that should share a thread. This setting is shared between all instances of this module, the last module to change it “wins”. Setting the value to -1 or 0 (the default) will result in an unlimited amount of instances sharing a single thread.

function eventsMaxModulesPerThread

int eventsMaxModulesPerThread() const

function clearInPorts

void clearInPorts()

function clearOutPorts

void clearOutPorts()

function removeInPortById

void removeInPortById(
    const QString & id
)

function removeOutPortById

void removeOutPortById(
    const QString & id
)

function inPorts

QList< std::shared_ptr< VarStreamInputPort > > inPorts() const

function outPorts

QList< std::shared_ptr< StreamOutputPort > > outPorts() const

function inPortById

std::shared_ptr< VarStreamInputPort > inPortById(
    const QString & id
) const

function outPortById

std::shared_ptr< StreamOutputPort > outPortById(
    const QString & id
) const

function intervalEventCallbacks

QList< QPair< intervalEventFunc_t, int > > intervalEventCallbacks() const

function recvDataEventCallbacks

QList< QPair< recvDataEventFunc_t, std::shared_ptr< VariantStreamSubscription > > > recvDataEventCallbacks() const

function serializeDisplayUiGeometry

QVariant serializeDisplayUiGeometry()

function restoreDisplayUiGeometry

void restoreDisplayUiGeometry(
    const QVariant & var
)

function setTimer

void setTimer(
    std::shared_ptr< SyncTimer > timer
)

Protected Functions Documentation

function raiseError

void raiseError(
    const QString & message
)

function setStatusMessage

void setStatusMessage(
    const QString & message
)

function makeDirectory

bool makeDirectory(
    const QString & dir
)

function appProcessEvents

void appProcessEvents()

function datasetNameSuggestion

QString datasetNameSuggestion(
    bool lowercase =true
) const

Suggested name for datasets from this module.

Creates a good name based on the modules human-chosen name for datasets generated by it. This includes removing special characters, like slashes, from the name and simplifying the name string in general.

Modules should use this function to choose a dataset name, but they may also decide to use a different, custom name.

function datasetNameFromSubMetadata

QString datasetNameFromSubMetadata(
    const QVariantHash & subMetadata
) const

Get name of a dataset from subscription metadata.

Some modules make a suggestion to their subscribers as for how they may want the stored data to be named. This function extracts a suitable dataset name from subscription metadata.

This function always returns a valid name, if no suggestion is given from the subscriber, the module’s name is used.

function datasetNameFromParameters

QString datasetNameFromParameters(
    const QString & preferredName,
    const QVariantHash & subMetadata
) const

Get name of a dataset from subscription metadata and preferred name.

This functions acts like datasetNameFromSubMetadata(), but will also try to use the supplied preferred name if possible.

This function always returns a valid name, if no suggestion is given from the subscriber, the module’s name is used.

function dataBasenameFromSubMetadata

QString dataBasenameFromSubMetadata(
    const QVariantHash & subMetadata,
    const QString & defaultName =QStringLiteral("data")
)

Get file basename for data from subscription metadata.

Some modules make a suggestion to their subscribers as for how they may want the stored data to be named. This function extracts a suitable file name from the metadata, which can be used in a dataset.

This function returns the “default” string if no suggestion was made.

function createDefaultDataset

std::shared_ptr< EDLDataset > createDefaultDataset(
    const QString & preferredName =QString(),
    const QVariantHash & subMetadata =QVariantHash()
)

Create dataset for data storage in default storage group for this module.

Parameters:

• preferredName The preferred name for the dataset.
• subMetadata Metadata from a stream subscription, in case using the desired name from a module upstream is wanted.

Create the default dataset with the given name for this module. The module can use it to get file paths to write data to. In case a module needs to create more then one dataset, creating a new group is advised first. Use the createStorageGroup() and createDatasetInGroup() methods for that.

This method will return NULL in case the module was not yet assigned a data storage group. Use it only in and after the PREPARE phase to get a valid dataset!

An error will be emitted if the requested dataset has already existed before, an NULL is returned in that case as well. This design exists to prevent two modules from trying to write to the same file.

function createDatasetInGroup

std::shared_ptr< EDLDataset > createDatasetInGroup(
    std::shared_ptr< EDLGroup > group,
    const QString & preferredName =QString(),
    const QVariantHash & subMetadata =QVariantHash()
)

function getDefaultDataset

std::shared_ptr< EDLDataset > getDefaultDataset()

Obtain the module’s default dataset if it exists.

If a default dataset has been created using createDefaultDataset(), return it. Otherwise return NULL.

function getDatasetInGroup

std::shared_ptr< EDLDataset > getDatasetInGroup(
    std::shared_ptr< EDLGroup > group,
    const QString & preferredName =QString(),
    const QVariantHash & subMetadata =QVariantHash()
)

function createStorageGroup

std::shared_ptr< EDLGroup > createStorageGroup(
    const QString & groupName
)

Create new data storage group with the given name.

Parameters:

• groupName Creates a new data storage group name, or retrieves a reference to the group in case one with this name already exists. The group is placed as child of the module’s default storage group.

This method will return NULL in case the module was not yet assigned a data storage group. Use it only in and after the PREPARE phase to get a valid dataset!

function addDisplayWindow

QWidget * addDisplayWindow(
    QWidget * window,
    bool owned =true
)

Register a display window for this module.

Parameters:

• window
• owned Add a new display window to this module. The window instance will be deleted on destruction, if #own was set to true.

function addSettingsWindow

QWidget * addSettingsWindow(
    QWidget * window,
    bool owned =true
)

Register a settings window for this module.

Parameters:

• window
• owned Add a new settings window to this module. The window instance will be deleted on destruction, if #own was set to true.

function registerTimedEvent

template <typename T >
inline void registerTimedEvent(
    void(T::*)(int &) fn,
    const milliseconds_t & interval
)

Request a member function of this module to be called at an interval.

Set a pointer to a member function of this module as first paremter, to be called at a interval set as second parameter in milliseconds. If the interval selected is 0, the function will be called as soon as possible.

The first parameter of the callback is a reference to the execution interval, which the callee may adjust to be run less or more frequent. Adjusting the frequency does not come at zero cost, so please avoid very frequent adjustments.

Since these functions are scheduled together with other possible events in an event loop, do not expect the member function to be called in exactly the requested intervals. The interval will also not be adjusted to “catch up” for lost time.

Please ensure that the callback function never blocks for an extended period of time to give other modules a chance to run as well. Also, you can expect this function to be run in a different thread compared to where the module’s prepare() function was run. The function may even move between threads, so make sure it is reentrant.

function registerDataReceivedEvent

template <typename T >
inline void registerDataReceivedEvent(
    void(T::*)() fn,
    std::shared_ptr< VariantStreamSubscription > subscription
)

Request a member function of this module to be called when a subscription has new data.

Set a pointer to a member function of this module as first parameter, to be called once the stream subscription given as second parameter has received more data.

Please ensure that the callback function never blocks for an extended period of time to give other modules a chance to run as well. Also, you can expect this function to be run in a different thread compared to where the module’s prepare() function was run. The function may even move between threads, so make sure it is reentrant.

function clearDataReceivedEventRegistrations

void clearDataReceivedEventRegistrations()

Remove all registered data-received event callbacks.

function initCounterSynchronizer

std::unique_ptr< FreqCounterSynchronizer > initCounterSynchronizer(
    double frequencyHz
)

Get new frequency/counter synchronizer.

This function can be called in the PREPARING phase of a module to retrieve a synchronizer for devices which have a continuous counter and a sampling frequency. A synchronizer can be used to semi-automatically synchronize a device timestamp or device clock with the master time. You will need to supply a fixed sampling rate in Hz for the given device, so the synchronizer can determine a timestamp for a sample index.

Returns: A new unique counter synchronizer, or NULL if we could not create one because no master timer existed.

function initClockSynchronizer

std::unique_ptr< SecondaryClockSynchronizer > initClockSynchronizer(
    double expectedFrequencyHz =0
)

Get new secondary clock synchronizer.

This function can be called in the PREPARING phase of a module to retrieve a synchronizer for devices which have an external clock to be synchronized and a known sampling frequency. A synchronizer can be used to semi-automatically synchronize a device clock with the master timer. The frequency of the secondary clock set here determines how many datapoints the synchronizer will store to calculate the divergence of the secondary clock time from master time. If set to zero, a fixed amount of timepoints will be used instead.

Since this synchronizer will only look at the difference between master and secondary clock time per measurement, the secondary clock may change its speed (as is the case with many cameras that don’t run at an exactly constant framerate but sometimes produce frames faster or slower than before)

Returns: A new unique clock synchronizer, or NULL if we could not create one because no master timer existed.

function potentialNoaffinityCPUCount

uint potentialNoaffinityCPUCount() const

Potential amount of CPUs not used by other syntalos tasks.

This is a rough guess and may not at all reflect reality. Modules may be interested in this information regardless, to scale the amount of external threads they themselves may create without control of Syntalos (in this event, it may be beneficial to give the user some control over this behavior, as it is impossible to know how heavy the workload of other modules on other threads actually is).

function defaultRealtimePriority

int defaultRealtimePriority() const

Default thread realtime priority.

Return: RT thread priority value

The default priority for realtime threads Syntalos is supposed to use. This value can be used if the module needs to manage its own realtime threads and wants to set the default priority on them (but managing threads on their own is generally discouraged for modules).

function isEphemeralRun

bool isEphemeralRun() const

Returns true if the currently ongoing or last run is/was ephemeral.

Return: True if the current run is/was ephemeral.

An emphameral (or volatile) run is a type of run where no data is stored permanently. Usually, a Syntalos module will not need to handle this type of run explicitly, but there are some cases where a module needs to be aware that all data will get deleted immediately after a run has completed (e.g. if postprocessing steps are deferred to an external process).

function usbHotplugEvent

virtual void usbHotplugEvent(
    UsbHotplugEventKind kind
)

Handle USB hotplug events.

This function is called by the engine when a new USB device appears or leaves. Its call is deferred when an experiment is running and dispatched after a run has completed.

function setInitialized

void setInitialized()

function initialized

bool initialized() const

Protected Attributes Documentation

variable m_running

std::atomic_bool m_running;

variable m_syTimer

std::shared_ptr< SyncTimer > m_syTimer;

Global master timer reference for this module, valid only during a run.

Friends

friend Engine

friend class Engine(
    Engine 
);

friend MLinkModule

friend class MLinkModule(
    MLinkModule 
);

Updated on 2024-09-05 at 17:39:59 +0000