A base-class for standard YARP modules that supports ResourceFinder. More...

#include <yarp/os/RFModule.h>

Classes
class	Private

Public Member Functions
	RFModule ()
	Constructor. More...

virtual	~RFModule ()
	Destructor. More...

virtual double	getPeriod ()
	You can override this to control the approximate periodicity at which updateModule() is called by runModule(). More...

virtual bool	updateModule ()=0
	Override this to do whatever your module needs to do. More...

virtual int	runModule ()
	Calls updateModule() until that returns false. More...

virtual int	runModule (yarp::os::ResourceFinder &rf)
	Simple helper method to call configure() and then runModule(). More...

virtual int	runModuleThreaded ()
	Calls updateModule() on a separate thread until that returns false. More...

virtual int	runModuleThreaded (yarp::os::ResourceFinder &rf)
	Simple helper method to call configure() and then runModule() on a separate thread. More...

virtual int	getThreadKey ()
	return the Thread unique identifier More...

virtual bool	configure (yarp::os::ResourceFinder &rf)
	Configure the module, pass a ResourceFinder object to the module. More...

virtual bool	respond (const Bottle &command, Bottle &reply)
	Respond to a message. More...

virtual bool	attach (yarp::os::Port &source)
	Make any input from a Port object go to the respond() method. More...

virtual bool	attach (yarp::os::RpcServer &source)
	Make any input from an RpcServer object go to the respond() method. More...

bool	attachTerminal ()
	Make any input from standard input (usually the keyboard) go to the respond() method. More...

bool	detachTerminal ()
	Detach terminal. More...

virtual bool	interruptModule ()
	Try to halt any ongoing operations by threads managed by the module. More...

virtual bool	close ()
	Close function. More...

void	stopModule (bool wait=false)
	Ask the module to stop. More...

bool	isStopping ()
	Check if the module should stop. More...

bool	joinModule (double seconds=-1)
	The function returns when the thread execution has completed. More...

std::string	getName (const std::string &subName="")
	Return name of module, as set with setName(). More...

void	setName (const char *name)
	Set the name of the module. More...

bool	safeRespond (const Bottle &command, Bottle &reply)
	Wrapper around respond() that is guaranteed to process system messages. More...

Detailed Description

A base-class for standard YARP modules that supports ResourceFinder.

Examples: os/image_process_module/image_process_module.cpp.

Definition at line 23 of file RFModule.h.

Constructor & Destructor Documentation

◆ RFModule()

RFModule::RFModule ( )

Constructor.

Definition at line 289 of file RFModule.cpp.

◆ ~RFModule()

RFModule::~RFModule ( )

virtual

Destructor.

Definition at line 313 of file RFModule.cpp.

Member Function Documentation

◆ attach() [1/2]

bool RFModule::attach ( yarp::os::Port & source )

virtual

Make any input from a Port object go to the respond() method.

Attach this object to a source of messages.

Parameters

source the port to attach

Returns: true if source was attached correctly.

Parameters

source a BufferedPort or PortReaderBuffer that receives data.

Definition at line 459 of file RFModule.cpp.

◆ attach() [2/2]

bool RFModule::attach ( yarp::os::RpcServer & source )

virtual

Make any input from an RpcServer object go to the respond() method.

Parameters

source the RpcServer port to attach

Returns: true if source was attached correctly.

Definition at line 466 of file RFModule.cpp.

◆ attachTerminal()

bool RFModule::attachTerminal ( )

Make any input from standard input (usually the keyboard) go to the respond() method.

The reply will be send to standard output.

Returns: true on success.

Definition at line 473 of file RFModule.cpp.

◆ close()

bool RFModule::close ( )

virtual

Close function.

This is called automatically when the module closes, after the last call to updateModule. Override this to cleanup memory allocated in the configure() function or perform other activities that ensure graceful shutdown.

Returns: true/false on success failure.

Definition at line 493 of file RFModule.cpp.

◆ configure()

bool RFModule::configure ( yarp::os::ResourceFinder & rf )

virtual

Configure the module, pass a ResourceFinder object to the module.

This function can perform initialization including object creation and memory allocation; returns false to notify that initialization was not successful and that the module should not start. Cleanup should be performed by the function close(). In case of failure during the initialization and before returning false, the function configure() should cleanup memory and resources allocated.

Parameters

rf	a previously initialized ResourceFinder

Returns: true/false upon success/failure

Note: attachTerminal() is no longer called automatically. You can call it in the configure function.

Definition at line 441 of file RFModule.cpp.

◆ detachTerminal()

bool RFModule::detachTerminal ( )

Detach terminal.

Definition at line 480 of file RFModule.cpp.

◆ getName()

std::string RFModule::getName ( const std::string & subName = "" )

Return name of module, as set with setName().

If a string is passed to the function, it gets concatenated to the module name. This function can be useful to form port names used by the module. Important: strings are concatenated "as they are", no slashes are appended at the beginning of the strings. To support legacy code the function will make sure subName contains a trailing slash (this behavior is deprecated and will disappear).

Parameters

subName get nested name with this at the end

Returns: the name of the module

Definition at line 534 of file RFModule.cpp.

◆ getPeriod()

double RFModule::getPeriod ( )

virtual

You can override this to control the approximate periodicity at which updateModule() is called by runModule().

By default, it returns 1.0. Time here is in seconds.

Returns: the desired period between successive calls to updateModule()

Definition at line 320 of file RFModule.cpp.

◆ getThreadKey()

int RFModule::getThreadKey ( )

virtual

return the Thread unique identifier

Definition at line 236 of file RFModule.cpp.

◆ interruptModule()

bool RFModule::interruptModule ( )

virtual

Try to halt any ongoing operations by threads managed by the module.

This is called asynchronously just after a quit command is received. By default it does nothing - you may want to override this. If you have created any ports, and have any threads that are might be blocked on reading data from those ports, this is a good place to add calls to BufferedPort::interrupt() or Port::interrupt().

Returns: true if there was no catastrophic failure

Definition at line 487 of file RFModule.cpp.

◆ isStopping()

bool RFModule::isStopping ( )

Check if the module should stop.

Returns: true/false if the module should stop or not.

Definition at line 513 of file RFModule.cpp.

◆ joinModule()

bool RFModule::joinModule ( double seconds = -1 )

The function returns when the thread execution has completed.

Stops the execution of the thread that calls this function until either the thread to join has finished execution (when it returns from run()) or after seconds seconds.

If RFModule has not been thredified, the function returns true immediately.

Parameters

seconds the maximum number of seconds to block the thread.

Returns: true if the thread execution is finished or when RFModule has not been thredified, false on time out.

Definition at line 519 of file RFModule.cpp.

◆ respond()

bool RFModule::respond	(	const Bottle &	command,
		Bottle &	reply
	)

virtual

Respond to a message.

You can override this to respond to messages in your own way. It is useful, if your module doesn't know what to do with a message, to call RFModule::respond() for any default responses.

Parameters

command	the message received
reply	the response you wish to make

Returns: true if there was no critical failure

Definition at line 448 of file RFModule.cpp.

◆ runModule() [1/2]

int RFModule::runModule ( )

virtual

Calls updateModule() until that returns false.

Make sure you first configure your module by calling the configure() function. updateModule() is then called every getPeriod() seconds. During execution of updateModule() the following methods may be executed asynchronously:

respond(): this is called if there is input from the standard input or a message from an input port connected to the module via attach().
interruptModule(): this method is called by the handlers of the following signals: SIGINT, SIGTERM and SIGBREAK (WIN32). Interrupt is a good place to execute code that unblocks pending reads (i.e. blocking reads on port).

After the last iteration of updateModule() the function close() is executed.

Returns: 0 on success

Note: attachTerminal() is no longer called automatically.

Definition at line 326 of file RFModule.cpp.

◆ runModule() [2/2]

int RFModule::runModule ( yarp::os::ResourceFinder & rf )

virtual

Simple helper method to call configure() and then runModule().

See documentation of configure() and runModule() for more details.

Parameters

rf	a previously initialized ResourceFinder

Returns: 0 upon success, non-zero upon failure

Definition at line 392 of file RFModule.cpp.

◆ runModuleThreaded() [1/2]

int RFModule::runModuleThreaded ( )

virtual

Calls updateModule() on a separate thread until that returns false.

Make sure you first configure your module by calling the configure() function. updateModule() is then called every getPeriod() seconds. During execution of updateModule() the following methods may be executed asynchronously:

respond(): this is called if there is input from the standard input or a message from an input port connected to the module via attach().
interruptModule(): this method is called by the handlers of the following signals: SIGINT, SIGTERM and SIGBREAK (WIN32). Interrupt is a good place to execute code that unblocks pending reads (i.e. blocking reads on port).

After the last iteration of updateModule() the function close() is executed.

Returns: 0 on success

Note: attachTerminal() is no longer called automatically.

Definition at line 406 of file RFModule.cpp.

◆ runModuleThreaded() [2/2]

int RFModule::runModuleThreaded ( yarp::os::ResourceFinder & rf )

virtual

Simple helper method to call configure() and then runModule() on a separate thread.

See documentation of configure() and runModule() for more details.

Parameters

rf	a previously initialized ResourceFinder

Returns: 0 upon success, non-zero upon failure

Definition at line 426 of file RFModule.cpp.

◆ safeRespond()

bool RFModule::safeRespond	(	const Bottle &	command,
		Bottle &	reply
	)

Wrapper around respond() that is guaranteed to process system messages.

Definition at line 562 of file RFModule.cpp.

◆ setName()

void RFModule::setName ( const char * name )

Set the name of the module.

Parameters

name	the desired name of the module

Definition at line 556 of file RFModule.cpp.

◆ stopModule()

void RFModule::stopModule ( bool wait = false )

Ask the module to stop.

Called automatically by signal handlers or when a quit message is received by the respond() (by the console or by a port if attached). It raises an internal flag that notifies the module to stop executing updateModule() and then calls interruptModule().

Parameters

wait	if RFModule is run threaded, specifies if stop should call join and wait for thread termination.

Definition at line 499 of file RFModule.cpp.

◆ updateModule()

virtual bool yarp::os::RFModule::updateModule ( )

pure virtual

Override this to do whatever your module needs to do.

When your module wants to stop, return false. The module's actual work could be done during this call, or it could just check the state of a thread running in the background.

The thread calls the updateModule() function every <period> seconds. At the end of each run, the thread will sleep the amounth of time required, taking into account the time spent inside the loop function. Example: requested period is 10ms, the updateModule() function take 3ms to be executed, the thread will sleep for 7ms.

Note: after each run is completed, the thread will call a yield() in order to facilitate other threads to run.

Returns: true iff module should continue

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

src/libYARP_os/src/yarp/os/RFModule.h
src/libYARP_os/src/yarp/os/RFModule.cpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RFModule()

◆ ~RFModule()

Member Function Documentation

◆ attach() [1/2]

◆ attach() [2/2]

◆ attachTerminal()

◆ close()

◆ configure()

◆ detachTerminal()

◆ getName()

◆ getPeriod()

◆ getThreadKey()

◆ interruptModule()

◆ isStopping()

◆ joinModule()

◆ respond()

◆ runModule() [1/2]

◆ runModule() [2/2]

◆ runModuleThreaded() [1/2]

◆ runModuleThreaded() [2/2]

◆ safeRespond()

◆ setName()

◆ stopModule()

◆ updateModule()