YARP
Yet Another Robot Platform
yarp::os::RFModule Class Referenceabstract

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

#include <yarp/os/RFModule.h>

Detailed Description

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

Examples:
os/image_process_module.cpp.

Definition at line 23 of file RFModule.h.

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

Private Member Functions

virtual bool basicRespond (const Bottle &command, Bottle &reply)
 

Private Attributes

ResourceFinder resourceFinder
 
void * implementation
 
bool stopFlag
 
std::string name
 

Constructor & Destructor Documentation

◆ RFModule()

RFModule::RFModule ( )

Constructor.

Definition at line 262 of file RFModule.cpp.

◆ ~RFModule()

RFModule::~RFModule ( )
virtual

Destructor.

Definition at line 284 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
sourcethe port to attach
Returns
true if source was attached correctly.
Parameters
sourcea BufferedPort or PortReaderBuffer that receives data.

Definition at line 425 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
sourcethe RpcServer port to attach
Returns
true if source was attached correctly.

Definition at line 431 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 437 of file RFModule.cpp.

◆ basicRespond()

bool RFModule::basicRespond ( const Bottle command,
Bottle reply 
)
privatevirtual

Definition at line 528 of file RFModule.cpp.

◆ close()

bool RFModule::close ( void  )
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 455 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
rfa 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 409 of file RFModule.cpp.

◆ detachTerminal()

bool RFModule::detachTerminal ( )

Detach terminal.

Definition at line 443 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
subNameget nested name with this at the end
Returns
the name of the module

Definition at line 492 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 294 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 450 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 471 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
secondsthe 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 476 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
commandthe message received
replythe response you wish to make
Returns
true if there was no critical failure

Definition at line 415 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 299 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
rfa previously initialized ResourceFinder
Returns
0 upon success, non-zero upon failure

Definition at line 369 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 380 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
rfa previously initialized ResourceFinder
Returns
0 upon success, non-zero upon failure

Definition at line 397 of file RFModule.cpp.

◆ setName()

void RFModule::setName ( const char *  name)

Set the name of the module.

Parameters
namethe desired name of the module

Definition at line 513 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
waitif RFModule is run threaded, specifies if stop should call join and wait for thread termination.

Definition at line 460 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

Member Data Documentation

◆ implementation

void* yarp::os::RFModule::implementation
private

Definition at line 284 of file RFModule.h.

◆ name

std::string yarp::os::RFModule::name
private

Definition at line 286 of file RFModule.h.

◆ resourceFinder

ResourceFinder yarp::os::RFModule::resourceFinder
private

Definition at line 283 of file RFModule.h.

◆ stopFlag

bool yarp::os::RFModule::stopFlag
private

Definition at line 285 of file RFModule.h.


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