RobotRaconteur::Generator< Return, Param > Class Template Reference

Generator type for use with generator functions, with parameter and return. More...

#include <Generator.h>

Inheritance diagram for RobotRaconteur::Generator< Return, Param >:

Public Member Functions
virtual Return	Next (const Param &v)=0
	Advance the generator.
virtual bool	TryNext (const Param &v, Return &ret)
	Try to advance the generator. Return false if no more values are available.
virtual void	AsyncNext (const Param &v, boost::function< void(const Return &, const boost::shared_ptr< RobotRaconteurException > &err)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously advance the generator.
virtual void	Abort ()=0
	Abort the generator.
virtual void	AsyncAbort (boost::function< void(const boost::shared_ptr< RobotRaconteurException > &err)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously abort the generator.
virtual void	Close ()=0
	Close the generator.
virtual void	AsyncClose (boost::function< void(const boost::shared_ptr< RobotRaconteurException > &err)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously closes the generator.

Detailed Description

template<typename Return, typename Param>
class RobotRaconteur::Generator< Return, Param >

Generator type for use with generator functions, with parameter and return.

Generators are used with generator functions to implement simple coroutines. They are returned by function members with a parameter and/or return marked with the generator container type. Robot Raconteur generators are modeled on Python generators, and are intended to be used in two scenarios:

1. Transfering large parameter values or return values that would be over the message transfer limit (typically around 10 MB).
2. Long running operations that return updates or require periodic input. Generators are used to implement functionality similar to "actions" in ROS.

Generators are a generalization of iterators, where a value is returned every time the iterator is advanced until there are no more values. Python and Robot Raconteur iterators add the option of passing a parameter every advance, allowing for simple coroutines. The generator is advanced by calling the Next() or AsyncNext() functions. These functions will either return a value or throw StopIterationException if there are no more values. Next() and AsyncNext() may also throw any valid Robot Raconteur exception.

Generators can be terminated with either the Close() or Abort() functions. Close() should be used to cleanly close the generator, and is not considered an error condition. Next(), if called after close, should throw StopIterationException. Abort() is considered an error condition, and will cause any action associated with the generator to be aborted as quickly as possible (ie faulting a robot). If Next() is called after Abort(), OperationAbortedException should be thrown.

Robot Raconteur clients will return a populated stub generator that calls the service. Services are expected to return a subclass of Generator that implements at a minimum Next(), Close(), and Abort(). AsyncNext(), AsyncAbort(), and AsyncClose() may optionally be implemented for asynchronous operation on the service side.

Template Parameters

Return	The type of value returned by Next() and AsyncNext()
Param	The type of the parameter passed to Next() and AsyncNext()

Member Function Documentation

Abort()

template<typename Return, typename Param>

virtual void RobotRaconteur::Generator< Return, Param >::Abort ( )

pure virtual

Abort the generator.

Aborts and destroys the generator. This is assumed to be an error condition. Next() should throw OperationAbortedException if called after Abort(). Any ongoing operations should be terminated with an error condition, for example a moving robot should be immediately halted.

Implemented in RobotRaconteur::RangeGenerator< T >, RobotRaconteur::SyncGenerator< Return, Param >, and RobotRaconteur::SyncGenerator< T::value_type, void >.

AsyncAbort()

template<typename Return, typename Param>

virtual void RobotRaconteur::Generator< Return, Param >::AsyncAbort ( boost::function< void(const boost::shared_ptr< RobotRaconteurException > &err)> handler, int32_t timeout = RR_TIMEOUT_INFINITE )

pure virtual

Asynchronously abort the generator.

Same as Abort() but returns asynchronously.

Parameters

handler	The handler to call when abort is complete
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout.

AsyncClose()

template<typename Return, typename Param>

virtual void RobotRaconteur::Generator< Return, Param >::AsyncClose ( boost::function< void(const boost::shared_ptr< RobotRaconteurException > &err)> handler, int32_t timeout = RR_TIMEOUT_INFINITE )

pure virtual

Asynchronously closes the generator.

Same as Close() but returns asynchronously.

Parameters

handler	The handler to call when close is complete
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout.

AsyncNext()

template<typename Return, typename Param>

virtual void RobotRaconteur::Generator< Return, Param >::AsyncNext ( const Param & v, boost::function< void(const Return &, const boost::shared_ptr< RobotRaconteurException > &err)> handler, int32_t timeout = RR_TIMEOUT_INFINITE )

pure virtual

Asynchronously advance the generator.

Same as Next() but returns asynchronously.

Parameters

v	Parameter to pass to generator
handler	A handler function to receive the return value or an exception
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout.

Implemented in RobotRaconteur::SyncGenerator< Return, Param >, and RobotRaconteur::SyncGenerator< T::value_type, void >.

Close()

template<typename Return, typename Param>

virtual void RobotRaconteur::Generator< Return, Param >::Close ( )

pure virtual

Close the generator.

Closes the generator. Closing the generator terminates iteration and destroys the generator. This operation cleanly closes the generator, and is not considered to be an error condition. Next() should throw StopIterationException if called after Close().

Implemented in RobotRaconteur::RangeGenerator< T >, RobotRaconteur::SyncGenerator< Return, Param >, and RobotRaconteur::SyncGenerator< T::value_type, void >.

Next()

template<typename Return, typename Param>

virtual Return RobotRaconteur::Generator< Return, Param >::Next ( const Param & v )

pure virtual

Advance the generator.

Next() advances the generator to retrieve the next value. This version of Generator includes passing a parameter v to the generator.

Parameters

v	Parameter to pass to generator

Returns

Return Return value from generator

Implemented in RobotRaconteur::SyncGenerator< Return, Param >, and RobotRaconteur::SyncGenerator< T::value_type, void >.

TryNext()

template<typename Return, typename Param>

virtual bool RobotRaconteur::Generator< Return, Param >::TryNext ( const Param & v, Return & ret )

inlinevirtual

Try to advance the generator. Return false if no more values are available.

TryNext() is similar to Next() but returns false if no more values are available. This is useful for generators that may not have a fixed number of values.

Parameters

v	Parameter to pass to generator
ret	Return value from generator

Returns

true ret is valid

false ret is not valid. No more values are available.

---

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

• /builddir/build/BUILD/robotraconteur-1.2.8-build/RobotRaconteur-1.2.8-Source/RobotRaconteurCore/include/RobotRaconteur/Generator.h