Class ClientSession
Defined in File client_session.h
Class Documentation
-
class ClientSession
The eCAL::sercice::ClientSession class represents the binary service client session.
The ClientSession can connect to exactly one service server. For multiple connections, multiple ClientSession instances are required.
The ClientSession needs an io_context to run. The io_context is not owned by the ClientSession and must be kept alive by the user, e.g. by a work object.
Upon creation, the ClientSession will connect to a server via the given address and port. Both synchronous and asynchronous service calls are available. The async service callbacks are executed by the io_context thread. Therefore, the callbacks must not block the io_context thread for too long.
Important: Do not stop the io_context while the client session is running. This may cause undefined behavior. Instead, call stop() and wait for the io_context to run out of work on its own.
Tip: Use the ecal_service::ClientManager class to manage the client’s lifecycle. This enables you to stop all client sessions from a single place when performing an application
shutdown.
Sample conde:
// Create an io_context and a work object to keep it alive auto io_context = std::make_shared<asio::io_context>(); asio::io_context::work work(*io_context); // Creat a thread for the io_context std::thread io_context_thread([&io_context]() { io_context->run(); }); // Create client sessions auto client_session = ecal_service::ClientSession::create(io_context, ...) // call a service asynchronously client_session->async_call_service(...); // DO STUFF // Stop the client session client_session->stop(); // Wait for the io_context to run out of work io_context_thread.join();
Public Types
-
using EventCallbackT = ClientEventCallbackT
-
using ResponseCallbackT = ClientResponseCallbackT
-
using DeleteCallbackT = std::function<void(ClientSession*)>
Public Functions
-
ClientSession(const ClientSession&) = delete
-
ClientSession &operator=(const ClientSession&) = delete
-
ClientSession(ClientSession&&) = delete
-
ClientSession &operator=(ClientSession&&) = delete
-
~ClientSession()
Calls the server asynchronously.
This function will call the server asynchronously. The response_callback will be called when the server responds. The response_callback will be called from the io_context thread. Therefore, the response_callback must not block the io_context thread for too long.
When an error occurs, the response_callback will be called with an error.
When the client has been stopped manually, this function will return false. In that case, the response_callback will not be called, as there is no way to make sure, that the io_context is still running.
- Parameters:
request – The request to send to the server.
response_callback – The callback to be called when the server responds or an error occurs.
- Returns:
true if the request was sent enqueued successfully, false otherwise. If this returns false, the response_callback will not be called.
Calls the server synchronously.
This function will call the server synchronously. The function will block until the server responds or an error occurs. The response will be written to the response parameter
If this function deadlocks, you must check that the io_context is running, as that is required for the this function to un-block. The io_context must therefore never been stopped. Instead, call stop() and wait for the io_context to run out of work on its own.
- Parameters:
request – The request to send to the server.
response – The server’s response
- Returns:
The error that occured or ecal_service::Error::OK if no error occured.
-
std::string get_host() const
Get the host that this client is connected to.
Get the host that this client is connected to. If the client is not connected, this function will return an empty string. Otherwise, it will return the hostname from the list server_list that the client is connected to.
The host is not resolved to an IP address. Use get_remote_endpoint() to get the actual IP address.
- Returns:
The host that this client is connected to.
-
std::uint16_t get_port() const
Get the port that this client session is connected to.
Get the port that this client session is connected to. If the client is not connected, this function will return 0. Otherwise, it will return the port from the list server_list that the client is connected to.
- Returns:
The port that this client is connected to
-
asio::ip::tcp::endpoint get_remote_endpoint() const
Get the remote endpoint that this client session is connected to.
Get the remote endpoint that this client session is connected to. Only valid, if the client session is actually connected to a server. If a hostname was given, this function will return the resolved IP address.
-
State get_state() const
Get the state of this client session.
- Returns:
the state of this client session.
-
std::uint8_t get_accepted_protocol_version() const
Get the accepted protocol version that the server and client have agreed on.
If the connection hasn’t been established yet, this function will return 0.
- Returns:
The accepted protocol version that the server and client have agreed on.
-
int get_queue_size() const
Get the number of pending requests.
- Returns:
The number of pending requests
-
void stop()
Stops the client session.
This function will stop the client session. The client session will disconnect from the server and will not accept any new requests. Any further calls to async_call_service() will fail with an error.
Once the client session has been stopped, it cannot be restarted. You must create a new client session instead.
Public Static Functions
Creates a new ClientSession instance.
A new ClientSession will immediatelly start connecting to a server on the given address and port.
Important: Do not stop the io_context while the client session is running. This may cause undefined behavior. Instead, call stop() and wait for the io_context to run out of work on its own.
Tip: Use the ecal_service::ClientManager class to manage the client’s lifecycle. This enables you to stop all client sessions from a single place when performing an application
shutdown.
- Parameters:
io_context – The io_context to use for the session and all callbacks.
protocol_version – The protocol version to use for the session. When this is 0, the legacy buggy protocol is used.
server_list – A list of endpoints to connect to. Must not be empty. The endpoints will be tried in the given order until a working endpoint is found.
event_callback – The callback to be called when the session’s state changes, i.e. when the session successfully connected to a server or disconnected from it.
logger – The logger to use for logging.
delete_callback – The callback to be called when the session is deleted. This is useful for the ecal_service::ClientManager to keep track of the number of active sessions.
- Returns:
The new ClientSession instance as a shared_ptr.
Protected Functions
-
using EventCallbackT = ClientEventCallbackT