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

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

#include <Generator.h>

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

Public Member Functions
virtual Return	Next ()=0
	Advance the generator.
virtual bool	TryNext (Return &ret)
	Try to advance the generator. Return false if no more values are available.
virtual void	AsyncNext (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.
virtual std::vector< Return >	NextAll ()
	Automatically call Next() repeatedly and return std::vector of results.

Detailed Description

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

Generator type for use with generator functions, with 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>

virtual void RobotRaconteur::Generator< Return, void >::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::SyncGenerator< Return, void >.

AsyncAbort()

template<typename Return>

virtual void RobotRaconteur::Generator< Return, void >::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>

virtual void RobotRaconteur::Generator< Return, void >::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>

virtual void RobotRaconteur::Generator< Return, void >::AsyncNext ( 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

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

Close()

template<typename Return>

virtual void RobotRaconteur::Generator< Return, void >::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::SyncGenerator< Return, void >.

Next()

template<typename Return>

virtual Return RobotRaconteur::Generator< Return, void >::Next ( )

pure virtual

Advance the generator.

Next() advances the generator to retrieve the next value. This version of Generator does not include passing a parameter to the generator.

Returns

Return Return value from generator

Implemented in RobotRaconteur::SyncGenerator< Return, void >.

NextAll()

template<typename Return>

virtual std::vector< Return > RobotRaconteur::Generator< Return, void >::NextAll ( )

inlinevirtual

Automatically call Next() repeatedly and return std::vector of results.

Returns

std::vector<Return> All values returned by generator Next()

TryNext()

template<typename Return>

virtual bool RobotRaconteur::Generator< Return, void >::TryNext ( 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 version of TryNext() does not include passing a parameter to the generator.

Parameters

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