wire member type interface More...

Inheritance diagram for RobotRaconteur::Wire< T >:

Public Member Functions
virtual boost::shared_ptr< WireConnection< T > >	Connect ()=0
	Connect the wire. More...

virtual void	AsyncConnect (boost::function< void(const boost::shared_ptr< WireConnection< T > > &, const boost::shared_ptr< RobotRaconteurException > &)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously connect the wire. More...

virtual T	PeekInValue (TimeSpec &ts)=0
	Peek the current InValue. More...

virtual T	PeekOutValue (TimeSpec &ts)=0
	Peek the current OutValue. More...

virtual void	PokeOutValue (const T &value)=0
	Poke the OutValue. More...

virtual void	AsyncPeekInValue (boost::function< void(const T &, const TimeSpec &, const boost::shared_ptr< RobotRaconteurException > &)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously peek the current InValue. More...

virtual void	AsyncPeekOutValue (boost::function< void(const T &, const TimeSpec &, const boost::shared_ptr< RobotRaconteurException > &)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously peek the current OutValue. More...

virtual void	AsyncPokeOutValue (const T &value, boost::function< void(const boost::shared_ptr< RobotRaconteurException > &)> handler, int32_t timeout=RR_TIMEOUT_INFINITE)=0
	Asynchronously poke the OutValue. More...

virtual boost::function< void(const boost::shared_ptr< WireConnection< T > > &)>	GetWireConnectCallback ()=0
	Get the currently configured wire connected callback function. More...

virtual void	SetWireConnectCallback (boost::function< void(const boost::shared_ptr< WireConnection< T > > &)> function)=0
	Set wire connected callback function. More...

virtual boost::function< T(const uint32_t &)>	GetPeekInValueCallback ()=0
	Get the currently configure PeekInValue callback. More...

virtual void	SetPeekInValueCallback (boost::function< T(const uint32_t &)> function)=0
	Set the PeekInValue callback function. More...

virtual boost::function< T(const uint32_t &)>	GetPeekOutValueCallback ()=0
	Get the currently configure PeekOutValue callback. More...

virtual void	SetPeekOutValueCallback (boost::function< T(const uint32_t &)> function)=0
	Set the PeekOutValue callback function. More...

virtual boost::function< void(const T &, const TimeSpec &, const uint32_t &)>	GetPokeOutValueCallback ()=0
	Get the currently configure PokeOutValue callback. More...

virtual void	SetPokeOutValueCallback (boost::function< void(const T &, const TimeSpec &, const uint32_t &)> function)=0
	Set the PokeOutValue callback function. More...

virtual std::string	GetMemberName ()=0
	Get the member name of the wire. More...

MemberDefinition_Direction	Direction ()
	The direction of the wire. More...

Detailed Description

template<typename T>
class RobotRaconteur::Wire< T >

wire member type interface

The Wire class implements the wire member type. Wires are declared in service definition files using the wire keyword within object declarations. Wires provide "most recent" value streaming between clients and services. They work by creating "connection" pairs between the client and service. The wire streams the current value between the wire connection pairs using packets. Wires are unreliable; only the most recent value is of interest, and any older values will be dropped. Wire connections have an InValue and an OutValue. Users set the OutValue on the connection. The new OutValue is transmitted to the peer wire connection, and becomes the peer's InValue. The peer can then read the InValue. The client and service have their own InValue and OutValue, meaning that each direction, client to service or service to client, has its own value.

Wire connections are created using the Connect() or AsyncConnect() functions. Services receive incoming connection requests through a callback function. Thes callback is configured using the SetWireConnectCallback() function. Services may also use the WireBroadcaster class or WireUnicastReceiver class to automate managing wire connection lifecycles. WireBroadcaster is used to send values to all connected clients. WireUnicastReceiver is used to receive the value from the most recent wire connection. See WireConnection for details on sending and receiving streaming values.

Wire clients may also optionally "peek" and "poke" the wire without forming a streaming connection. This is useful if the client needs to read the InValue or set the OutValue instantaniously, but does not need continuous updating. PeekInValue() or AsyncPeekInValue() will retrieve the client's current InValue. PokeOutValue() or AsyncPokeOutValue() will send a new client OutValue to the service. PeekOutValue() or AsyncPeekOutValue() will retrieve the last client OutValue received by the service.

"Peek" and "poke" operations initiated by the client are received on the service using callbacks. Use SetPeekInValueCallback(), SetPeekOutValueCallback(), and SetPokeOutValueCallback() to configure the callbacks to handle these requests. WireBroadcaster and WireUnicastReceiver configure these callbacks automatically, so the user does not need to configure the callbacks when these classes are used.

Wires can be declared readonly or writeonly. If neither is specified, the wire is assumed to be full duplex. readonly pipes may only send values from service to client, ie OutValue on service side and InValue on client side. writeonly pipes may only send values from client to service, ie OutValue on client side and InValue on service side. Use Direction() to determine the direction of the wire.

Unlike pipes, wire connections are not indexed, so only one connection pair can be created per client connection.

WireBroadcaster or WireUnicastReceiver are typically used to simplify using wires. See WireBroadcaster and WireUnicastReceiver for more information.

This class is instantiated by the node. It should not be instantiated by the user.

Template Parameters

T	The value data type

Member Function Documentation

◆ AsyncConnect()

template<typename T >

virtual void RobotRaconteur::Wire< T >::AsyncConnect	(	boost::function< void(const boost::shared_ptr< WireConnection< T > > &, const boost::shared_ptr< RobotRaconteurException > &)>	handler,
		int32_t	timeout = `RR_TIMEOUT_INFINITE`
	)

pure virtual

Asynchronously connect the wire.

Same as Connect(), but returns asynchronously

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

handler	A handler function to receive the wire connection, or an exception
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

◆ AsyncPeekInValue()

template<typename T >

virtual void RobotRaconteur::Wire< T >::AsyncPeekInValue	(	boost::function< void(const T &, const TimeSpec &, const boost::shared_ptr< RobotRaconteurException > &)>	handler,
		int32_t	timeout = `RR_TIMEOUT_INFINITE`
	)

pure virtual

Asynchronously peek the current InValue.

Same as PeekInValue(), but returns asynchronously.

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

handler	A handler function to receive the InValue and timestamp, or an exception
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

◆ AsyncPeekOutValue()

template<typename T >

virtual void RobotRaconteur::Wire< T >::AsyncPeekOutValue	(	boost::function< void(const T &, const TimeSpec &, const boost::shared_ptr< RobotRaconteurException > &)>	handler,
		int32_t	timeout = `RR_TIMEOUT_INFINITE`
	)

pure virtual

Asynchronously peek the current OutValue.

Same as PeekOutValue(), but returns asynchronously.

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

handler	A handler function to receive the OutValue and timestamp, or an exception
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

◆ AsyncPokeOutValue()

template<typename T >

virtual void RobotRaconteur::Wire< T >::AsyncPokeOutValue	(	const T &	value,
		boost::function< void(const boost::shared_ptr< RobotRaconteurException > &)>	handler,
		int32_t	timeout = `RR_TIMEOUT_INFINITE`
	)

pure virtual

Asynchronously poke the OutValue.

Same as PokeOutValue(), but returns asynchronously

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

handler	A handler function to invoke on completion, with possible exception
value	The new OutValue
timeout	Timeout in milliseconds, or RR_TIMEOUT_INFINITE for no timeout

◆ Connect()

template<typename T >

virtual boost::shared_ptr<WireConnection<T> > RobotRaconteur::Wire< T >::Connect ( )

pure virtual

Connect the wire.

Creates a connection between the wire, returning the client connection. Used to create a "most recent" value streaming connection to the service.

Only valid on clients. Will throw InvalidOperationException on the service side.

Note: If a streaming connection is not required, use PeekInValue(), PeekOutValue(), or PokeOutValue() instead of creating a connection.

Returns: RR_SHARED_PTR<WireConnection<T> > The wire connection

◆ Direction()

MemberDefinition_Direction RobotRaconteur::WireBase::Direction ( )

inherited

The direction of the wire.

Wires may be declared readonly or writeonly in the service definition file. (If neither is specified, the wire is assumed to be full duplex.) readonly wire may only send out values from service to client. writeonly wires may only send out values from client to service.

Returns: MemberDefinition_Direction

◆ GetMemberName()

virtual std::string RobotRaconteur::WireBase::GetMemberName ( )

pure virtualinherited

Get the member name of the wire.

Returns: std::string

◆ GetPeekInValueCallback()

template<typename T >

virtual boost::function<T(const uint32_t&)> RobotRaconteur::Wire< T >::GetPeekInValueCallback ( )

pure virtual

Get the currently configure PeekInValue callback.

Only valid for services. Will throw InvalidOperationException on the client side.

Returns: boost::function<T(const uint32_t&)> The currently configured callback function

◆ GetPeekOutValueCallback()

template<typename T >

virtual boost::function<T(const uint32_t&)> RobotRaconteur::Wire< T >::GetPeekOutValueCallback ( )

pure virtual

Get the currently configure PeekOutValue callback.

Only valid for services. Will throw InvalidOperationException on the client side.

Returns: boost::function<T(const uint32_t&)> The currently configured callback function

◆ GetPokeOutValueCallback()

template<typename T >

virtual boost::function<void(const T&, const TimeSpec&, const uint32_t&)> RobotRaconteur::Wire< T >::GetPokeOutValueCallback ( )

pure virtual

Get the currently configure PokeOutValue callback.

Only valid for services. Will throw InvalidOperationException on the client side.

Returns: boost::function<void(const T&, const TimeSpec&, const uint32_t&)> The currently configured callback function

◆ GetWireConnectCallback()

template<typename T >

virtual boost::function<void(const boost::shared_ptr<WireConnection<T> >&)> RobotRaconteur::Wire< T >::GetWireConnectCallback ( )

pure virtual

Get the currently configured wire connected callback function.

Only valid for services. Will throw InvalidOperationException on client side.

Returns: boost::function<void(RR_SHARED_PTR<WireConnection<T> >)> The currently configured callback function

◆ PeekInValue()

template<typename T >

virtual T RobotRaconteur::Wire< T >::PeekInValue ( TimeSpec & ts )

pure virtual

Peek the current InValue.

Peeks the current InValue using a "request" instead of a streaming value. Use if only the instantanouse value is required.

Peek and poke are similar to property members. Unlike streaming, peek and poke are reliable operations.

Throws ValueNotSetException if InValue is not valid.

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

ts	[out] The timestamp of the current InValue

Returns: T The current InValue

◆ PeekOutValue()

template<typename T >

virtual T RobotRaconteur::Wire< T >::PeekOutValue ( TimeSpec & ts )

pure virtual

Peek the current OutValue.

Peeks the current OutValue using a "request" instead of a streaming value. Use if only the instantanouse value is required.

Peek and poke are similar to property members. Unlike streaming, peek and poke are reliable operations.

Throws ValueNotSetException if OutValue is not valid.

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

ts	[out] The timestamp of the current OutValue

Returns: T The current OutValue

◆ PokeOutValue()

template<typename T >

virtual void RobotRaconteur::Wire< T >::PokeOutValue ( const T & value )

pure virtual

Poke the OutValue.

Pokes the OutValue using a "request" instead of a streaming value. Use to update the OutValue if the value is updated infrequently.

Peek and poke are similar to property members. Unlike streaming, peek and poke are reliable operations.

Only valid on clients. Will throw InvalidOperationException on the service side.

Parameters

value The new OutValue

◆ SetPeekInValueCallback()

template<typename T >

virtual void RobotRaconteur::Wire< T >::SetPeekInValueCallback ( boost::function< T(const uint32_t &)> function )

pure virtual

Set the PeekInValue callback function.

Peek and poke operations are used when a streaming connection of the most recent value is not required. Clients initiate peek and poke operations using PeekInValue(), PeekOutValue(), PokeOutValue(), or their asynchronous equivalents. Services receive the peek and poke requests through callbacks.

SetPeekInValueCallback() configures the service callback for PeekInValue() requests.

The specified callback function should have the following signature:

T peek_invalue_callback(uint32 client_endpoint);

The function receives the client endpoint ID, and returns the current InValue.

Note: Callback is configured automatically by WireBroadcaster or WireUnicastReceiver

Only valid for services. Will throw InvalidOperationException on the client side.

Parameters

function The callback function

◆ SetPeekOutValueCallback()

template<typename T >

virtual void RobotRaconteur::Wire< T >::SetPeekOutValueCallback ( boost::function< T(const uint32_t &)> function )

pure virtual

Set the PeekOutValue callback function.

Peek and poke operations are used when a streaming connection of the most recent value is not required. Clients initiate peek and poke operations using PeekInValue(), PeekOutValue(), PokeOutValue(), or their asynchronous equivalents. Services receive the peek and poke requests through callbacks.

SetPeekOutValueCallback() configures the service callback for PeekOutValue() requests.

The specified callback function should have the following signature:

T peek_outvalue_callback(uint32 client_endpoint);

The function receives the client endpoint ID, and returns the current OutValue.

Note: Callback is configured automatically by WireBroadcaster or WireUnicastReceiver

Only valid for services. Will throw InvalidOperationException on the client side.

Parameters

function The callback function

◆ SetPokeOutValueCallback()

template<typename T >

virtual void RobotRaconteur::Wire< T >::SetPokeOutValueCallback ( boost::function< void(const T &, const TimeSpec &, const uint32_t &)> function )

pure virtual

Set the PokeOutValue callback function.

Peek and poke operations are used when a streaming connection of the most recent value is not required. Clients initiate peek and poke operations using PeekInValue(), PeekOutValue(), PokeOutValue(), or their asynchronous equivalents. Services receive the peek and poke requests through callbacks.

SetPokeOutValueCallback() configures the service callback for PokeOutValue() requests.

The specified callback function should have the following signature:

void poke_outvalue_callback(const T& value, const TimeSpec& timestamp, uint32 client_endpoint);

The function receives the new out value, the new out value timestamp in the client's clock, and the client endpoint ID.

Note: Callback is configured automatically by WireBroadcaster or WireUnicastReceiver

Only valid for services. Will throw InvalidOperationException on the client side.

Parameters

function The callback function

◆ SetWireConnectCallback()

template<typename T >

virtual void RobotRaconteur::Wire< T >::SetWireConnectCallback ( boost::function< void(const boost::shared_ptr< WireConnection< T > > &)> function )

pure virtual

Set wire connected callback function.

Callback function invoked when a client attempts to connect a the wire. The callback will receive the incoming wire connection as a parameter. The service must maintain a reference to the wire connection, but the wire will retain ownership of the wire connection until it is closed. Using boost::weak_ptr to store the reference to the connection is recommended.

The callback may throw an exception to reject incoming connect request.

Note: Connect callback is configured automatically by WireBroadcaster or WireUnicastReceiver

Only valid for services. Will throw InvalidOperationException on the client side.

Parameters

function Callback function to receive the incoming connection

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

/home/runner/work/robotraconteur/robotraconteur/robotraconteur/RobotRaconteurCore/include/RobotRaconteur/WireMember.h

Public Member Functions

Detailed Description

template<typename T> class RobotRaconteur::Wire< T >

Member Function Documentation

◆ AsyncConnect()

◆ AsyncPeekInValue()

◆ AsyncPeekOutValue()

◆ AsyncPokeOutValue()

◆ Connect()

◆ Direction()

◆ GetMemberName()

◆ GetPeekInValueCallback()

◆ GetPeekOutValueCallback()

◆ GetPokeOutValueCallback()

◆ GetWireConnectCallback()

◆ PeekInValue()

◆ PeekOutValue()

◆ PokeOutValue()

◆ SetPeekInValueCallback()

◆ SetPeekOutValueCallback()

◆ SetPokeOutValueCallback()

◆ SetWireConnectCallback()

template<typename T>
class RobotRaconteur::Wire< T >