Syntalos::MLinkModule

Master link for out-of-process modules.

#include <mlinkmodule.h>

Inherits from Syntalos::AbstractModule, QObject

Public Types

	Name
enum	OutChannelType { ChannelAll, ChannelStdout, ChannelStderr}

Public Signals

	Name
void	processOutputReceived(OutChannelType channel, const QString & text)

Public Functions

	Name
	MLinkModule(QObject * parent =nullptr)
	~MLinkModule() override
virtual bool	initialize() override Initialize the module.
virtual ModuleDriverKind	driver() const override Select how this module will be executed by the Syntalos engine.
virtual ModuleFeatures	features() const override Return a bitfield of features this module supports.
QString	moduleBinary() const
void	setModuleBinary(const QString & binaryPath)
void	setModuleBinaryArgs(const QStringList & args)
void	setModuleBinaryWorkDir(const QString & wdir)
QProcessEnvironment	moduleBinaryEnv() const
void	setModuleBinaryEnv(const QProcessEnvironment & env)
ModuleWorkerMode	workerMode() const
void	setWorkerMode(ModuleWorkerMode mode)
bool	outputCaptured() const
void	setOutputCaptured(bool capture)
void	setPythonVirtualEnv(const QString & venvDir)
void	setScript(const QString & script, const QString & wdir =QString())
bool	setScriptFromFile(const QString & fname, const QString & wdir =QString())
virtual void	serializeSettings(const QString & confBaseDir, QVariantHash & settings, QByteArray & extraData) override Serialize the settings of this module.
virtual bool	loadSettings(const QString & confBaseDir, const QVariantHash & settings, const QByteArray & extraData) override Load settings from previously stored data.
virtual void	showDisplayUi() override Show the display widgets of this module.
virtual void	showSettingsUi() override Show the configuration UI of this module.
void	terminateProcess()
bool	runProcess()
bool	isProcessRunning() const
bool	loadCurrentScript(bool resetPorts =false)
bool	sendPortInformation()
QString	readProcessOutput(OutChannelType channel =ChannelAll)
void	markIncomingForExport(StreamExporter * exporter)
virtual bool	prepare(const TestSubject & testSubject) override Prepare for an experiment run.
virtual void	start() override Run when the experiment is started and the HRTimer has an initial time set. Switches the module into “Started” mode.
virtual void	stop() override Stop running an experiment. Stop execution of an experiment. This method is called after prepare() was run.
virtual void	runThread(OptionalWaitCondition * startWaitCondition) override Run task in a thread.

Protected Functions

	Name
bool	testIpcApiVersion(bool emitErrors =true)
void	handleIncomingControl()

Friends

	Name
class	Private

Additional inherited members

Public Signals inherited from Syntalos::AbstractModule

	Name
void	stateChanged(ModuleState state)
void	error(const QString & message)
void	statusMessage(const QString & message)
void	nameChanged(const QString & name)
void	portsConnected(const VarStreamInputPort * inPort, const StreamOutputPort * outPort)
void	portConfigurationUpdated()
void	synchronizerDetailsChanged(const std::string & id, const Syntalos::TimeSyncStrategies & strategies, const Syntalos::microseconds_t & tolerance)
void	synchronizerOffsetChanged(const std::string & id, const Syntalos::microseconds_t & currentOffset)
void	modifiersUpdated()

Public Functions inherited from Syntalos::AbstractModule

	Name
	AbstractModule(const ModuleInfo * info =nullptr, QObject * parent =nullptr)
	AbstractModule(QObject * parent =nullptr)
	~AbstractModule() override
ModuleState	state() const
void	setStateDormant() Allow a running module to mark itself as idle.
void	setStateReady() Allow a preparing module to mark itself as ready.
QString	id() const Name of this module used internally as unique identifier.
int	index() const Index of this module.
virtual QString	name() const Name of this module displayed to the user.
virtual void	setName(const QString & name)
template <typename T > std::shared_ptr< DataStream< T > >	registerOutputPort(const QString & id, const QString & title =QString()) Register an output port for this module.
template <typename T > std::shared_ptr< StreamInputPort< T > >	registerInputPort(const QString & id, const QString & title =QString()) Register an input port for this module.
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.
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.
void	updateCommonStreamMetadata() Update the common metadata of all output streams of this module.
virtual void	processUiEvents() Called to process UI events.
virtual void	finalize() Finalize this module. This method is called before the module itself is destroyed.
virtual bool	isDisplayUiVisible()
virtual bool	isSettingsUiVisible()
virtual void	hideDisplayUi() Hide all display widgets of this module.
virtual void	hideSettingsUi() Hide the configuration UI of this module.
virtual void	inputPortConnected(VarStreamInputPort * inPort) Called when one of this module’s input ports is subscribed to a stream.
virtual void	updateStartWaitCondition(OptionalWaitCondition * waitCondition) Update thread start wait condition before each run.
QString	lastError() const Return last error.
QString	moduleRootDir() const Obtain the root directory of this (loadable) module.
void	setEventsMaxModulesPerThread(int maxModuleCount) Set maximum modules per thread when using dedicated event driver.
int	eventsMaxModulesPerThread() const
void	clearInPorts()
void	clearOutPorts()
void	removeInPortById(const QString & id)
void	removeOutPortById(const QString & id)
QList< std::shared_ptr< VarStreamInputPort > >	inPorts() const
QList< std::shared_ptr< StreamOutputPort > >	outPorts() const
std::shared_ptr< VarStreamInputPort >	inPortById(const QString & id) const
std::shared_ptr< StreamOutputPort >	outPortById(const QString & id) const
QList< QPair< intervalEventFunc_t, int > >	intervalEventCallbacks() const
QList< QPair< recvDataEventFunc_t, std::shared_ptr< VariantStreamSubscription > > >	recvDataEventCallbacks() const
QVariant	serializeDisplayUiGeometry()
void	restoreDisplayUiGeometry(const QVariant & var)
void	setTimer(std::shared_ptr< SyncTimer > timer)
ModuleModifiers	modifiers() const Return a bitfield of modifiers assigned to this module.
void	setModifiers(ModuleModifiers modifiers)

Protected Functions inherited from Syntalos::AbstractModule

	Name
void	raiseError(const QString & message)
void	setStatusMessage(const QString & message)
bool	makeDirectory(const QString & dir)
void	appProcessEvents()
QString	datasetNameSuggestion(bool lowercase =true) const Suggested name for datasets from this module.
QString	datasetNameFromSubMetadata(const MetaStringMap & subMetadata) const Get name of a dataset from subscription metadata.
QString	datasetNameFromParameters(const QString & preferredName, const MetaStringMap & subMetadata) const Get name of a dataset from subscription metadata and preferred name.
QString	dataBasenameFromSubMetadata(const MetaStringMap & subMetadata, const QString & defaultName =QStringLiteral(“data”)) Get file basename for data from subscription metadata.
std::string	dataBasenameFromSubMetadata(const MetaStringMap & subMetadata, const std::string & defaultName =“data”)
std::shared_ptr< EDLDataset >	createDefaultDataset(const QString & preferredName ={}, const MetaStringMap & subMetadata ={}) Create dataset for data storage in default storage group for this module.
std::shared_ptr< EDLDataset >	createDatasetInGroup(std::shared_ptr< EDLGroup > group, const QString & preferredName ={}, const MetaStringMap & subMetadata ={})
std::shared_ptr< EDLDataset >	createDefaultDataset(const std::string & preferredName, const MetaStringMap & subMetadata ={})
std::shared_ptr< EDLDataset >	createDatasetInGroup(std::shared_ptr< EDLGroup > group, const std::string & preferredName, const MetaStringMap & subMetadata ={})
std::shared_ptr< EDLDataset >	getDefaultDataset() Obtain the module’s default dataset if it exists.
std::shared_ptr< EDLGroup >	createStorageGroup(const QString & groupName) Create new data storage group with the given name.
QWidget *	addDisplayWindow(QWidget * window, bool owned =true) Register a display window for this module.
QWidget *	addSettingsWindow(QWidget * window, bool owned =true) Register a settings window for this module.
template <typename T > void	registerTimedEvent(void(T::*)(int &) fn, const milliseconds_t & interval) Request a member function of this module to be called at an interval.
template <typename T > 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.
template <typename Callable > void	registerDataReceivedEvent(Callable && fn, std::shared_ptr< VariantStreamSubscription > subscription) Request an arbitrary callable to be called when a subscription has new data.
void	clearDataReceivedEventRegistrations() Remove all registered data-received event callbacks.
std::unique_ptr< FreqCounterSynchronizer >	initCounterSynchronizer(double frequencyHz) Get new frequency/counter synchronizer.
std::unique_ptr< SecondaryClockSynchronizer >	initClockSynchronizer(double expectedFrequencyHz =0) Get new secondary clock synchronizer.
uint	potentialNoaffinityCPUCount() const Potential amount of CPUs not used by other syntalos tasks.
int	defaultRealtimePriority() const Default thread realtime priority.
int	defaultThreadNiceness() const Returns the thread niceness value for this run.
bool	isEphemeralRun() const Returns true if the currently ongoing or last run is/was ephemeral.
virtual void	usbHotplugEvent(UsbHotplugEventKind kind) Handle USB hotplug events.
void	setInitialized()
bool	initialized() const

Protected Attributes inherited from Syntalos::AbstractModule

	Name
QuillLogger *	m_log
std::atomic_bool	m_running
std::shared_ptr< SyncTimer >	m_syTimer Global master timer reference for this module, valid only during a run.

Friends inherited from Syntalos::AbstractModule

	Name
class	Engine

Public Types Documentation

enum OutChannelType

Enumerator	Value	Description
ChannelAll
ChannelStdout
ChannelStderr

Public Signals Documentation

signal processOutputReceived

void processOutputReceived(
    OutChannelType channel,
    const QString & text
)

Public Functions Documentation

function MLinkModule

explicit MLinkModule(
    QObject * parent =nullptr
)

function ~MLinkModule

~MLinkModule() override

function initialize

virtual bool initialize() override

Initialize the module.

Return: true if success

Reimplements: Syntalos::AbstractModule::initialize

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 driver

virtual ModuleDriverKind driver() const override

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

Reimplements: Syntalos::AbstractModule::driver

function features

virtual ModuleFeatures features() const override

Return a bitfield of features this module supports.

Reimplements: Syntalos::AbstractModule::features

function moduleBinary

QString moduleBinary() const

function setModuleBinary

void setModuleBinary(
    const QString & binaryPath
)

function setModuleBinaryArgs

void setModuleBinaryArgs(
    const QStringList & args
)

function setModuleBinaryWorkDir

void setModuleBinaryWorkDir(
    const QString & wdir
)

function moduleBinaryEnv

QProcessEnvironment moduleBinaryEnv() const

function setModuleBinaryEnv

void setModuleBinaryEnv(
    const QProcessEnvironment & env
)

function workerMode

ModuleWorkerMode workerMode() const

function setWorkerMode

void setWorkerMode(
    ModuleWorkerMode mode
)

function outputCaptured

bool outputCaptured() const

function setOutputCaptured

void setOutputCaptured(
    bool capture
)

function setPythonVirtualEnv

void setPythonVirtualEnv(
    const QString & venvDir
)

function setScript

void setScript(
    const QString & script,
    const QString & wdir =QString()
)

function setScriptFromFile

bool setScriptFromFile(
    const QString & fname,
    const QString & wdir =QString()
)

function serializeSettings

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

Serialize the settings of this module.

Reimplements: Syntalos::AbstractModule::serializeSettings

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
) override

Load settings from previously stored data.

Return: true if successful.

Reimplements: Syntalos::AbstractModule::loadSettings

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

function showDisplayUi

virtual void showDisplayUi() override

Show the display widgets of this module.

Reimplements: Syntalos::AbstractModule::showDisplayUi

function showSettingsUi

virtual void showSettingsUi() override

Show the configuration UI of this module.

Reimplements: Syntalos::AbstractModule::showSettingsUi

function terminateProcess

void terminateProcess()

function runProcess

bool runProcess()

function isProcessRunning

bool isProcessRunning() const

function loadCurrentScript

bool loadCurrentScript(
    bool resetPorts =false
)

function sendPortInformation

bool sendPortInformation()

function readProcessOutput

QString readProcessOutput(
    OutChannelType channel =ChannelAll
)

function markIncomingForExport

void markIncomingForExport(
    StreamExporter * exporter
)

function prepare

virtual bool prepare(
    const TestSubject & testSubject
) override

Prepare for an experiment run.

Return: true if success

Reimplements: Syntalos::AbstractModule::prepare

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

function start

virtual void start() override

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

Reimplements: Syntalos::AbstractModule::start

function stop

virtual void stop() override

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

Reimplements: Syntalos::AbstractModule::stop

function runThread

virtual void runThread(
    OptionalWaitCondition * startWaitCondition
) override

Run task in a thread.

Return: true if no error

Reimplements: Syntalos::AbstractModule::runThread

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).

Protected Functions Documentation

function testIpcApiVersion

bool testIpcApiVersion(
    bool emitErrors =true
)

function handleIncomingControl

void handleIncomingControl()

Process all pending IPC control messages from the worker.

Drains error, state-change, port-change and settings-change channels. Subclasses may call this after operations that are expected to trigger port registrations (e.g. after loading a script in Python modules).

Friends

friend Private

friend class Private(
    Private 
);

Updated on 2026-04-24 at 23:36:58 +0000

Syntalos::MetaValue Syntalos::ModuleInfo