User manual

old releases - latest release - trunk

PeekabotClient Class Reference

Inheritance diagram for PeekabotClient:

Inheritance graph
[legend]
Collaboration diagram for PeekabotClient:

Collaboration graph
[legend]

List of all members.

Detailed Description

Encapsulates a connection to a peekabot server.

Public Member Functions

Blocking methods
void connect (const std::string &hostname, unsigned int port=5050, bool low_latency_mode=false) throw (std::runtime_error)
 Connect the client to a peekabot server.
void disconnect (bool discard_unsent=false) throw ()
 Disconnect the client from the peekabot server.
void flush () throw ()
 Block until all outbound data has been sent.
void sync () throw ()
 Block until all prior operations have been executed in the peekabot server.
Non-blocking methods
bool is_connected () const throw ()
 Returns true if the client is connected to a server, false otherwise.
uint32_t waiting_actions () throw ()
 Returns the number of actions that are waiting to be sent from the client.
DelayedDispatch noop () throw ()
 Perform a no-op on the peekabot server.
void begin_bundle () throw ()
 Begin a bundle.
DelayedDispatch end_bundle () throw (std::runtime_error)
 End a bundle.
bool is_bundling () const throw ()
 Returns true if and only if the client is currently bundling operations.

Private Member Functions

void dispatch_action (Action *action, Status *status, bool bypass_bundling=false) const throw ()
 Dispatch an action.
boost::shared_ptr
< OperationResult > 		dispatch_get_action (Action *action, uint32_t request_id, bool bypass_bundling=false) const throw ()
 Dispatch a get action, i.e. an action returning data from the server.

Private Attributes

ClientImpl * m_impl
 The lower level client implementation.
Bundle * m_active_bundle
 The currently active bundle, or set to null if no bundle is active.

Friends

class DelayedDispatch
class PeekabotProxyBase

Member Function Documentation

void connect ( const std::string &  hostname,
unsigned int  port = 5050,
bool  low_latency_mode = false 
) throw (std::runtime_error)

Connect the client to a peekabot server.

If the client is already connected, this method is a no-op.

Unlike most other client API methods, this particular method is synchronous. It will initiate a connection with the server given, and go through the authentication process before returning.

Note that the client can be used prior to connecting to the peekabot server - operations requested before the client is connected will be queued and dispatched as soon as the client is connected.

Exceptions:
AuthenticationFailed Thrown when authentication with the server fails (probably beacause the other end is in fact not a peekabot server, or the server and client are incompatible).
HostResolveFailed Thrown when the given hostname cannot be resolved.
ConnectionRefused Thrown when a connection to the host could not be established.

void disconnect ( bool  discard_unsent = false  )  throw ()

Disconnect the client from the peekabot server.

If the client is not connected, this method is a no-op.

If there are unsent actions when disconnect() is called, they will be sent prior to disconnecting from the server, unless discard_unsent is set. If there's an active bundle, it will be ended before sending the outbound actions.

This method is blocking.

Parameters:
discard_unsent If set, unsent actions will be discarded rather than sent before disconnecting.

void flush (  )  throw ()

Block until all outbound data has been sent.

If the connection is terminated during a call to flush, the method will return, even though not all actions were sent.

void sync (  )  throw ()

Block until all prior operations have been executed in the peekabot server.

If the connection is terminated during a call to sync, the method will return, even though not all actions were sent or a response received from the server.

Remarks:
sync() will execute immediately, even if there's an active bundle. This behaviour guarantees that the calling application won't hang when syncing inside a bundle.
See also:
flush()

DelayedDispatch noop (  )  throw ()

Perform a no-op on the peekabot server.

This is useful for synchronization purposes: 

 peekabot::Status s = client.noop().status();
 ...
 s.wait_until_completed();

As illustrated above, this provides, for example, a way to make sure that the data from the last frame was received and processed - this approach, by nature, yields a smaller delay than using sync().

void begin_bundle (  )  throw ()

Begin a bundle.

Any operations issued between a call to begin_bundle() and end_bundle() are bundled up and sent first when end_bundle() os called.

Bundles are atomic in the sense that all the operations contained in the bundle are guaranteed to be executed between two frames. E.g. you won't see strange effects that a newly added object is drawn once before you have the time to set its scale and pose appropriately.

In addition, all operations are guaranteed to execute sequentially "without interruption" - operations from other clients are never interleaved.

Calling begin_bundle() while already bundling will implicitly end the previous bundle.

See also:
end_bundle(), is_bundling()

DelayedDispatch end_bundle (  )  throw (std::runtime_error)

End a bundle.

Exceptions:
std::runtime_error Thrown if the client currently isn't bundling operations (is_bundling() == false).

void dispatch_action ( Action *  action,
Status *  status,
bool  bypass_bundling = false 
) const throw () [private]

Dispatch an action.

Will encapsulate the action in a monitor if status is non-zero, which can then subsequently be used to track the action's outcome.

If there's an active bundle, the dispatched action will be added to it unless the bypass_bundling flags is set. If not, it will be forwarded to m_impl for immediate serialization and sending.

Parameters:
action The action to be dispatched.
status An optional status object pointer, if non-null the action will be tracked and the outcome available in status.
bypass_bundling If true, the action will be sent at once even if bundling is active.

boost::shared_ptr< OperationResult > dispatch_get_action ( Action *  action,
uint32_t  request_id,
bool  bypass_bundling = false 
) const throw () [private]

Dispatch a get action, i.e. an action returning data from the server.

Parameters:
action The action to be dispatched.
status request_id The request ID of the given action.
bypass_bundling If true, the action will be sent at once even if bundling is active.

Member Data Documentation

Bundle* m_active_bundle [private]

The currently active bundle, or set to null if no bundle is active.

See also:
begin_bundle(), end_bundle()

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