RobotRaconteur::PipeSubscription< T > Class Template Reference

Subscription for pipe members that aggregates incoming packets from client pipe endpoints. More...

#include <Subscription.h>

Inheritance diagram for RobotRaconteur::PipeSubscription< T >:

Public Member Functions
T	ReceivePacket ()
	Dequeue a packet from the receive queue.
bool	TryReceivePacket (T &packet)
	Try dequeuing a packet from the receive queue.
bool	TryReceivePacketWait (T &packet, int32_t timeout=RR_TIMEOUT_INFINITE, bool peek=false, boost::shared_ptr< PipeEndpoint< T > > *ep=NULL)
	Try dequeuing a packet from the receive queue, optionally waiting or peeking the packet.
void	AsyncSendPacketAll (const T &packet)
	Sends a packet to all connected pipe endpoints.
event_connection	AddPipePacketReceivedListener (boost::function< void(const boost::shared_ptr< PipeSubscription< T > > &)> f)
	Adds a pipe packet received event listener function.
size_t	Available ()
	Get the number of packets available to receive.
size_t	GetActivePipeEndpointCount ()
	Get the number of pipe endpoints currently connected.
bool	GetIgnoreReceived ()
	Get if incoming packets are currently being ignored.
void	SetIgnoreReceived (bool ignore)
	Set if incoming packets should be ignored.
void	Close ()
	Closes the pipe subscription.

Detailed Description

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

Subscription for pipe members that aggregates incoming packets from client pipe endpoints.

Pipe subscriptions are created using the ServiceSubscription::SubscribePipe() function. This function takes the the type of the pipe packets, the name of the pipe member, and an optional service path of the service object that owns the pipe member.

Pipe subscriptions collect all incoming packets from connect pipe endpoints. When a client connects, the pipe subscription will automatically connect a pipe endpoint the pipe endpoint specified when the PipeSubscription was created using ServiceSubscription::SubscribePipe(). The packets received from each of the collected pipes are collected and placed into a common receive queue. This queue is read using ReceivePacket(), TryReceivePacket(), or TryReceivePacketWait(). The number of packets available to receive can be checked using Available().

Pipe subscriptions can also be used to send packets to all connected pipe endpoints. This is done with the AsyncSendPacketAll() function. This function behaves somewhat like a "reverse broadcaster", sending the packets to all connected services.

If the pipe subscription is being used to send packets but not receive them, the SetIgnoreInValue() should be set to true to prevent packets from queueing.

Template Parameters

T	The type of the pipe packets

Member Function Documentation

AddPipePacketReceivedListener()

template<typename T>

event_connection RobotRaconteur::PipeSubscription< T >::AddPipePacketReceivedListener ( boost::function< void(const boost::shared_ptr< PipeSubscription< T > > &)> f )

inline

Adds a pipe packet received event listener function.

Add a listener function that is called when the pipe subscription receives a packet. The callback should have the signature:

void cb(PipeSubscriptionPtr<T> pipe_subscription)

The callback function does not include the received packets as an argument. The callback must call one of the ReceivePacket() functions to dequeue the packets.

Parameters

f	The callback function

Returns

event_connection The Boost.Signals2 connection

AsyncSendPacketAll()

template<typename T>

void RobotRaconteur::PipeSubscription< T >::AsyncSendPacketAll ( const T & packet )

inline

Sends a packet to all connected pipe endpoints.

Calls AsyncSendPacket() on all connected pipe endpoints with the specified value. Returns immediately, not waiting for transmission to complete.

Parameters

packet

The packet to send

Available()

size_t RobotRaconteur::PipeSubscriptionBase::Available ( )

inherited

Get the number of packets available to receive.

Use ReceivePacket(), TryReceivePacket(), or TryReceivePacketWait() to receive the packet

Returns

size_t

Close()

void RobotRaconteur::PipeSubscriptionBase::Close ( )

inherited

Closes the pipe subscription.

Pipe subscriptions are automatically closed when the parent ServiceSubscription is closed or when the node is shut down.

GetActivePipeEndpointCount()

size_t RobotRaconteur::PipeSubscriptionBase::GetActivePipeEndpointCount ( )

inherited

Get the number of pipe endpoints currently connected.

Returns

size_t The number of active pipe endpoints

GetIgnoreReceived()

bool RobotRaconteur::PipeSubscriptionBase::GetIgnoreReceived ( )

inherited

Get if incoming packets are currently being ignored.

Returns

true Incoming packets are being ignored

false Incoming packets are not being ignored

ReceivePacket()

template<typename T>

T RobotRaconteur::PipeSubscription< T >::ReceivePacket ( )

inline

Dequeue a packet from the receive queue.

If the receive queue is empty, an InvalidOperationException() is thrown

Returns

T The dequeued packet

SetIgnoreReceived()

void RobotRaconteur::PipeSubscriptionBase::SetIgnoreReceived ( bool ignore )

inherited

Set if incoming packets should be ignored.

See PipeEndpoint::SetIgnoreReceived();

If true, receivedpackets will be ignored for all connected pipe endpoints

Parameters

ignore

TryReceivePacket()

template<typename T>

bool RobotRaconteur::PipeSubscription< T >::TryReceivePacket ( T & packet )

inline

Try dequeuing a packet from the receive queue.

Same as ReceivePacket(), but returns a bool for success or failure instead of throwing an exception

Parameters

packet

[out] the dequeued packet

Returns

true The packet was dequeued successfully

false The queue is empty

TryReceivePacketWait()

template<typename T>

bool RobotRaconteur::PipeSubscription< T >::TryReceivePacketWait ( T & packet, int32_t timeout = RR_TIMEOUT_INFINITE, bool peek = false, boost::shared_ptr< PipeEndpoint< T > > * ep = NULL )

inline

Try dequeuing a packet from the receive queue, optionally waiting or peeking the packet.

Parameters

packet	[out] the dequeued packet
timeout	The time to wait for a packet to be received in milliseconds if the queue is empty, or RR_TIMEOUT_INFINITE to wait forever
peek	If true, the packet is returned, but not dequeued. If false, the packet is dequeued
ep	[out] the PipeEndpoint that received the packet

Returns

true The packet was dequeued successfully

false The receive queue is empty, or wait for packet timed out

---

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/Subscription.h