YARP  2.3.68+272-20170522.1+git50f0ae7
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>

+ Inheritance diagram for yarp::os::RFModule:

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...
 
ConstString getName (const ConstString &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
 
ConstString name
 

Detailed Description

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

Examples:
os/image_process_module.cpp.

Definition at line 26 of file RFModule.h.

Constructor & Destructor Documentation

◆ RFModule()

RFModule::RFModule ( )

Constructor.

Definition at line 352 of file RFModule.cpp.

◆ ~RFModule()

RFModule::~RFModule ( )
virtual

Destructor.

Definition at line 373 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 506 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 512 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 518 of file RFModule.cpp.

◆ basicRespond()

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

Definition at line 609 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 536 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.

Reimplemented in KinectThread.

Definition at line 491 of file RFModule.cpp.

◆ detachTerminal()

bool RFModule::detachTerminal ( )

Detach terminal.

Definition at line 524 of file RFModule.cpp.

◆ getName()

ConstString RFModule::getName ( const ConstString 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 573 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()

Reimplemented in KinectThread.

Definition at line 382 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 531 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 552 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 557 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 496 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 387 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 451 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 462 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 479 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 594 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 541 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.

Returns
true iff module should continue

Implemented in KinectThread.

Member Data Documentation

◆ implementation

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

Definition at line 278 of file RFModule.h.

◆ name

ConstString yarp::os::RFModule::name
private

Definition at line 280 of file RFModule.h.

◆ resourceFinder

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

Definition at line 277 of file RFModule.h.

◆ stopFlag

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

Definition at line 279 of file RFModule.h.


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