Wire Member

Wire Class

class RobotRaconteur.Wire

“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 PeekInValueCallback, PeekOutValueCallback, and PokeOutValueCallback 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.

AsyncConnect(handler, timeout=-1)

Asynchronously connect the wire

Same as Connect(), but returns asynchronously

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

If handler is None, returns an awaitable future.

Parameters:

• handler (Callable[[RobotRaconteur.WireConnection,Exception],None]) – A handler function to receive the wire connection, or an exception

• timeout – Timeout in seconds, or -1 for infinite

AsyncPeekInValue(handler, timeout=-1)

Asynchronously peek the current InValue

Same as PeekInValue(), but returns asynchronously.

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

Parameters:

• handler (Callable[[T,RobotRaconteur.TimeSpec,Exception],None]) – A handler function to receive the InValue and timestamp, or an exception

• timeout (float) – Timeout in seconds, or -1 for infinite

AsyncPeekOutValue(handler, timeout=-1)

Asynchronously peek the current OutValue

Same as PeekOutValue(), but returns asynchronously.

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

Parameters:

• handler (Callable[[T,RobotRaconteur.TimeSpec,Exception],None]) – A handler function to receive the OutValue and timestamp, or an exception

• timeout (float) – Timeout in seconds, or -1 for infinite

AsyncPokeOutValue(value, handler, timeout=-1)

Asynchronously poke the OutValue

Same as PokeOutValue(), but returns asynchronously

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

Parameters:

• handler (Callable[[Exception],None]) – A handler function to invoke on completion, with possible exception

• value – The new OutValue

• timeout (float) – Timeout in seconds, or -1 for no timeout

Connect()

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:

The wire connection

Return type:

RobotRaconteur.WireConnection

property Direction

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” wires may only send packets from service to client. “writeonly” wires may only send packets from client to service.

See MemberDefinition_Direction constants for possible return values.

Return type:

int

property MemberName

Get the member name of the wire

Return type:

str

PeekInValue()

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.

Return type:

Tuple[T,RobotRaconteur.TimeSpec]

property PeekInValueCallback

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.

PeekInValueCallback configures the service callback for PeekInValue() requests.

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.

Return type:

Callable[[int],T]

PeekOutValue()

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.

Return type:

Tuple[T,RobotRaconteur.TimeSpec]

property PeekOutValueCallback

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.

PeekOutValueCallback configures the service callback for PeekOutValue() requests.

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.

Return type:

Callable[[int],T]

PokeOutValue(value)

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

property PokeOutValueCallback

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.

PokeOutValueCallback configures the service callback for PokeOutValue() requests.

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.

Return type:

Callable[[T,RobotRaconteur.TimeSpec,int],None]

property WireConnectCallback

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.

Return type:

Callable[[RobotRaconteur.WireConnection],None]

WireConnection Class

class RobotRaconteur.WireConnection

Wire connection used to transmit “most recent” values

Wire connections are used to transmit “most recent” values between connected wire members. See Wire for more information on wire members.

Wire connections are created by clients using the Wire.Connect() or Wire.AsyncConnect() functions. Services receive incoming wire connection requests through a callback function specified using the Wire.WireConnectCallback property. Services may also use the WireBroadcaster class to automate managing wire connection lifecycles and sending values to all connected clients, or use WireUnicastReceiver to receive an incoming value from the most recently connected client.

Wire connections are used to transmit “most recent” values between clients and services. Connection the wire creates a connection pair, one in the client, and one in the service. Each wire connection object has an InValue and an OutValue. Setting the OutValue of one will cause the specified value to be transmitted to the InValue of the peer. See Wire for more information.

Values can optionally be specified to have a finite lifespan using InValueLifespan and OutValueLifespan. Lifespans can be used to prevent using old values that have not been recently updated.

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

AsyncClose(handler, timeout=2)

Asynchronously close the wire connection

Same as Close() but returns asynchronously

Parameters:

• handler (Callable[[Exception],None]) – A handler function to call on completion, possibly with an exception

• timeout (float) – Timeout in seconds, or -1 for infinite

Close()

Close the wire connection

Close the wire connection. Blocks until close complete. The peer wire connection is destroyed automatically.

property Direction

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” wires may only send packets from service to client. “writeonly” wires may only send packets from client to service.

See MemberDefinition_Direction constants for possible return values.

Return type:

int

property Endpoint

Get the Robot Raconteur node Endpoint ID

Gets the endpoint associated with the ClientContext or ServerEndpoint associated with the wire connection.

Return type:

int

property IgnoreInValue

Set whether wire connection should ignore incoming values

Wire connections may optionally desire to ignore incoming values. This is useful if the connection is only being used to send out values, and received values may create a potential memory . If ignore is true, incoming values will be discarded.

Return type:

bool

property InValue

Get the current InValue

Gets the current InValue that was transmitted from the peer. Throws ValueNotSetException if no value has been received, or the most recent value lifespan has expired.

property InValueLifespan

Set the lifespan of InValue

InValue may optionally have a finite lifespan specified in seconds. Once the lifespan after reception has expired, the InValue is cleared and becomes invalid. Attempts to access InValue will result in ValueNotSetException.

InValue lifespans may be used to avoid using a stale value received by the wire. If the lifespan is not set, the wire will continue to return the last received value, even if the value is old.

Specify -1 for infinite lifespan.

Return type:

float

property InValueValid

Get if the InValue is valid

The InValue is valid if a value has been received and the value has not expired

Return type:

bool

property LastValueReceivedTime

Get the timestamp of the last received value

Returns the timestamp of the value in the senders clock

Return type:

RobotRaconteur.TimeSpec

property LastValueSentTime

Get the timestamp of the last sent value

Returns the timestamp of the last sent value in the local clock

Return type:

RobotRaconteur.TimeSpec

property OutValue

Set the OutValue and transmit to the peer connection

Sets the OutValue for the wire connection. The specified value will be transmitted to the peer, and will become the peers InValue. The transmission is unreliable, meaning that values may be dropped if newer values arrive.

The most recent OutValue may also be read through this property.

property OutValueLifespan

Set the lifespan of OutValue

OutValue may optionally have a finite lifespan specified in seconds. Once the lifespan after sending has expired, the OutValue is cleared and becomes invalid. Attempts to access OutValue will result in ValueNotSetException.

OutValue lifespans may be used to avoid using a stale value sent by the wire. If the lifespan is not set, the wire will continue to return the last sent value, even if the value is old.

Specify -1 for infinite lifespan.

Return type:

float

property OutValueValid

Get if the OutValue is valid

The OutValue is valid if a value has been set using the OutValue property

Return type:

bool

TryGetInValue()

Try getting the InValue, returning true on success or false on failure

Get the current InValue and InValue timestamp. Return true or false on success or failure instead of throwing exception.

Returns:

Tuple of success, in value, and timespec

Return type:

Tuple[bool,T,RobotRaconteur.TimeSpec]

TryGetOutValue()

Try getting the OutValue, returning true on success or false on failure

Get the current OutValue and OutValue timestamp. Return true or false on success and failure instead of throwing exception.

Returns:

Tuple of success, out value, and timespec

Return type:

Tuple[bool,T,RobotRaconteur.TimeSpec]

WaitInValueValid(timeout=-1)

Waits for InValue to be valid

Blocks the current thread until InValue is valid, with an optional timeout. Returns true if InValue is valid, or false if timeout occurred.

Parameters:

timeout – Timeout in seconds, or -1 for infinite

Returns:

Value is valid

Return type:

bool

WaitOutValueValid(timeout=-1)

Waits for OutValue to be valid

Blocks the current thread until OutValue is valid, with an optional timeout. Returns true if OutValue is valid, or false if timeout occurred.

Parameters:

timeout – Timeout in seconds, or -1 for infinite

Returns:

Value is valid

Return type:

bool

property WireValueChanged

Event hook for wire value change. Use to add handlers to be called when the InValue changes.

def my_handler(con, value, ts):
   # Handle new value
   pass

my_wire_connection.WireValueChanged += my_handler

Handler must have signature Callable[[RobotRaconteur.WireConnection,T,RobotRaconteur.TimeSpec],None]

Return type:

RobotRaconteur.EventHook

WireBroadcaster Class

class RobotRaconteur.WireBroadcaster(wire)

Broadcaster to send values to all connected clients

WireBroadcaster is used by services to send values to all connected client endpoints. It attaches to the wire on the service side, and manages the lifecycle of connections. WireBroadcaster should only we used with wires that are declared readonly, since it has no provisions for receiving incoming values from clients.

WireBroadcaster is initialized by the user, or by default if the service object does not contain an attribute for the wire member. The default will automatically instantiate unicast receivers for wires marked readonly. If default the implementation is not not used, the broadcaster must be instantiated manually. It is recommended this be done using an RRServiceObjectInit() function in the service object. This function is called after the wires have been instantiated by the service.

Use OutValue property to broadcast values to all connected clients.

The rate that packets are sent can be regulated using a callback function configured with the SetPredicate() function, or using the BroadcastDownsampler class.

Parameters:

wire (RobotRaconteur.Wire) – The wire to use for broadcasting. Must be a wire from a service object. Specifying a client wire will result in an exception.

property ActiveWireConnectionCount

Get the number of active wire connections

property OutValue

Set the OutValue for all connections

Sets the OutValue for all connections. This will transmit the value to all connected clients using packets. The value will become the clients’ InValue.

The value will be returned when clients call Wire.PeekInValue() or Wire.AsyncPeekInValue()

property OutValueLifespan

Set the lifespan of OutValue

OutValue may optionally have a finite lifespan specified in seconds. Once the lifespan after sending has expired, the OutValue is cleared and becomes invalid. Attempts to access OutValue will result in ValueNotSetException.

OutValue lifespans may be used to avoid using a stale value sent by the wire. If the lifespan is not set, the wire will continue to return the last sent value, even if the value is old.

Specify -1 for no expiration.

property PeekInValueCallback

Set the PeekInValue callback function for the WireBrodcaster. Overrides the default callback that returns the last set OutValue.

Return type:

Callable[[int],T]

SetPredicate(f)

Set the predicate callback function

A predicate is optionally used to regulate when values are sent to clients. This is used by the BroadcastDownsampler to regulate update rates of values sent to clients.

The predicate callback is invoked before the broadcaster sends a value to an endpoint. If the predicate returns true, the value will be sent. If it is false, the value will not be sent to that endpoint.

The predicate receives the broadcaster and the client endpoint ID. It returns true to send the value, or false to not send the value.

Parameters:

f (Callable[[RobotRaconteur.WireBroadcaster,int],bool]) – The predicate

WireUnicastReceiver Class

class RobotRaconteur.WireUnicastReceiver(wire)

Receive the InValue from the most recent connection

WireUnicastReceiver is used by services to receive a value from a single client. When a client sets its OutValue, this value is transmitted to the service using packets, and becomes the service’s InValue for that connection. Service wires can have multiple active clients, so the service needs to choose which connection is “active”. The WireUnicastReceiver selects the “most recent” connection, and returns that connection’s InValue. Any existing connections are closed. WireUnicastReceiver should only be used with wires that are declared writeonly. It is recommended that object locks be used to protect from concurrent access when unicast receivers are used.

WireUnicastReceiver is initialized by the user, or by default if the service object does not contain an attribute for the wire member. The default will automatically instantiate unicast receivers for wires marked writeonly. If default the implementation is not not used, the unicast receiver must be instantiated manually. It is recommended this be done using an RRServiceObjectInit() function in the service object. This function is called after the wires have been instantiated by the service.

The current InValue is received using the InValue property or TryGetInValue(). The InValueChanged event hook can be used to monitor for changes to the InValue.

Clients may also use PokeOutValue() or AsyncPokeOutValue() to update the unicast receiver’s value.

Parameters:

wire (RobotRaconteur.Wire) – The wire to use for receiving. Must be a wire from a service object. Specifying a client wire will result in an exception.

property InValue

Get the current InValue

Gets the current InValue that was received from the active connection. Throws ValueNotSetException if no value has been received, or the most recent value lifespan has expired.

Return type:

Tuple[T,RobotRaconteur.TimeStamp]

property InValueChanged

Event hook for wire value change. Use to add handlers to be called when the InValue changes.

def my_handler(con, value, ts):
   # Handle new value
   pass

my_wire_connection.WireValueChanged += my_handler

Handler must have signature Callable[[T,RobotRaconteur.TimeSpec,int],None]

property InValueLifespan

Set the lifespan of InValue

InValue may optionally have a finite lifespan specified in seconds, or -1 for infinite. Once the lifespan after reception has expired, the InValue is cleared, and becomes invalid. Attempts to access InValue will result in a ValueNotSetException.

Return type:

float

TryGetInValue()

Try getting the current InValue, returning true on success or false on failure

Gets the current InValue, its timestamp, and the client that owns the connection. Returns True if value is valid, or False if value is invalid. Value will be invalid if no value has been received, or the value lifespan has expired.

Return type:

Tuple[bool,T,RobotRaconteur.TimeSpec,object]