PeekabotClient Class Reference


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:
- src/client/PeekabotClient.hh
- src/client/PeekabotClient.cc