A top-level container of connections, sessions, and links. More...
#include <container.hpp>
Public Member Functions | |
container (messaging_handler &handler, const std::string &id) | |
Create a container with a global handler for messaging events. | |
container (messaging_handler &handler) | |
Create a container with a global handler for messaging events. | |
container (const std::string &id) | |
Create a container. | |
container () | |
Create a container. | |
~container () | |
Destroy a container. | |
returned< connection > | connect (const std::string &conn_url, const connection_options &conn_opts) |
Connect to `conn_url` and send an open request to the remote peer. | |
returned< connection > | connect (const std::string &conn_url) |
Connect to `conn_url` and send an open request to the remote peer. | |
listener | listen (const std::string &listen_url, listen_handler &handler) |
Listen for new connections on `listen_url`. | |
listener | listen (const std::string &listen_url, const connection_options &conn_opts) |
Listen for new connections on `listen_url`. | |
listener | listen (const std::string &listen_url) |
Listen for new connections on `listen_url`. | |
void | run () |
Run the container in the current thread. | |
void | run (int count) |
Run the container with a pool of `count` threads, including the current thread. | |
void | auto_stop (bool enabled) |
Enable or disable automatic container stop. | |
void | stop (const error_condition &err) |
Stop the container with error condition `err`. | |
void | stop () |
Stop the container with an empty error condition. | |
returned< sender > | open_sender (const std::string &addr_url) |
Open a connection and sender for `addr_url`. | |
returned< sender > | open_sender (const std::string &addr_url, const proton::sender_options &snd_opts) |
Open a connection and sender for `addr_url`. | |
returned< sender > | open_sender (const std::string &addr_url, const connection_options &conn_opts) |
Open a connection and sender for `addr_url`. | |
returned< sender > | open_sender (const std::string &addr_url, const proton::sender_options &snd_opts, const connection_options &conn_opts) |
Open a connection and sender for `addr_url`. | |
returned< receiver > | open_receiver (const std::string &addr_url) |
Open a connection and receiver for `addr_url`. | |
returned< receiver > | open_receiver (const std::string &addr_url, const proton::receiver_options &rcv_opts) |
Open a connection and receiver for `addr_url`. | |
returned< receiver > | open_receiver (const std::string &addr_url, const connection_options &conn_opts) |
Open a connection and receiver for `addr_url`. | |
returned< receiver > | open_receiver (const std::string &addr_url, const proton::receiver_options &rcv_opts, const connection_options &conn_opts) |
Open a connection and receiver for `addr_url`. | |
std::string | id () const |
A unique identifier for the container. | |
void | client_connection_options (const connection_options &conn_opts) |
Connection options applied to outgoing connections. | |
connection_options | client_connection_options () const |
void | server_connection_options (const connection_options &conn_opts) |
Connection options applied to incoming connections. | |
connection_options | server_connection_options () const |
void | sender_options (const class sender_options &snd_opts) |
Sender options applied to senders created by this container. | |
class sender_options | sender_options () const |
void | receiver_options (const class receiver_options &rcv_opts) |
Receiver options applied to receivers created by this container. | |
class receiver_options | receiver_options () const |
void | schedule (duration dur, work fn) |
Schedule `fn` for execution after a duration. | |
void | schedule (duration dur, void_function0 &fn) |
**Deprecated** - Use `containerschedule(duration, work)`. |
A top-level container of connections, sessions, and links.
A container gives a unique identity to each communicating peer. It is often a process-level object.
It also serves as an entry point to the API, allowing connections, senders, and receivers to be established. It can be supplied with an event handler in order to intercept important messaging events, such as newly received messages or newly issued credit for sending messages.
broker.cpp, client.cpp, direct_recv.cpp, direct_send.cpp, helloworld.cpp, multithreaded_client.cpp, multithreaded_client_flow_control.cpp, scheduled_send.cpp, scheduled_send_03.cpp, server.cpp, server_direct.cpp, service_bus.cpp, simple_recv.cpp, and simple_send.cpp.
container | ( | messaging_handler & | handler, | |
const std::string & | id | |||
) |
Create a container with a global handler for messaging events.
Thread safety** - in a multi-threaded container this handler will be called concurrently. You can use locks to make that safe, or use a separate handler for each connection. See mt_page.
handler | global handler, called for events on all connections managed by the container. | |
id | sets the container's unique identity. |
container | ( | messaging_handler & | handler | ) |
Create a container with a global handler for messaging events.
Thread safety** - in a multi-threaded container this handler will be called concurrently. You can use locks to make that safe, or use a separate handler for each connection. See mt_page.
handler | global handler, called for events on all connections managed by the container. |
container | ( | const std::string & | id | ) |
Create a container.
id | sets the container's unique identity. |
~container | ( | ) |
returned<connection> connect | ( | const std::string & | conn_url, | |
const connection_options & | conn_opts | |||
) |
Connect to `conn_url` and send an open request to the remote peer.
Options are applied to the connection as follows.
1. client_connection_options() 2. Options passed to connect()
Values in later options override earlier ones. The handler in the composed options is used to call `messaging_handleron_connection_open()` when the open response is received from the remote peer.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<connection> connect | ( | const std::string & | conn_url | ) |
Connect to `conn_url` and send an open request to the remote peer.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
listener listen | ( | const std::string & | listen_url, | |
listen_handler & | handler | |||
) |
Listen for new connections on `listen_url`.
If the listener opens successfully, listen_handler::on_open() is called. If it fails to open, listen_handler::on_error() then listen_handler::close() are called.
listen_handler::on_accept() is called for each incoming connection to determine the connection_options to use, including the messaging_handler.
Thread safety** - Calls to `listen_handler` methods are serialized for this listener, but handlers attached to separate listeners may be called concurrently.
listener listen | ( | const std::string & | listen_url, | |
const connection_options & | conn_opts | |||
) |
Listen for new connections on `listen_url`.
Use a fixed set of options for all accepted connections. See listen(const std::string&, listen_handler&).
Thread safety** - for multi-threaded applications we recommend using a listen_handler to create a new messaging_handler for each connection. See listen(const std::string&, listen_handler&) and mt_page
listener listen | ( | const std::string & | listen_url | ) |
Listen for new connections on `listen_url`.
New connections will use the handler from `server_connection_options()`. See listen(const std::string&, const connection_options&);
void run | ( | ) |
Run the container in the current thread.
The call returns when the container stops. See `auto_stop()` and `stop()`.
C++ versions** - With C++11 or later, you can call `run()` in multiple threads to create a thread pool. See also `run(int count)`.
void run | ( | int | count | ) |
void auto_stop | ( | bool | enabled | ) |
void stop | ( | const error_condition & | err | ) |
Stop the container with error condition `err`.
This function initiates shutdown and immediately returns. The shutdown process has the following steps.
void stop | ( | ) |
Stop the container with an empty error condition.
This function initiates shutdown and immediately returns. The shutdown process has the following steps.
When the process is complete, `run()` returns in all threads.
Thread safety** - It is safe to call this method in any thread.
Open a connection and sender for `addr_url`.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<sender> open_sender | ( | const std::string & | addr_url, | |
const proton::sender_options & | snd_opts | |||
) |
Open a connection and sender for `addr_url`.
Supplied sender options will override the container's template options.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<sender> open_sender | ( | const std::string & | addr_url, | |
const connection_options & | conn_opts | |||
) |
Open a connection and sender for `addr_url`.
Supplied connection options will override the container's template options.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<sender> open_sender | ( | const std::string & | addr_url, | |
const proton::sender_options & | snd_opts, | |||
const connection_options & | conn_opts | |||
) |
Open a connection and sender for `addr_url`.
Supplied sender or connection options will override the container's template options.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
Open a connection and receiver for `addr_url`.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<receiver> open_receiver | ( | const std::string & | addr_url, | |
const proton::receiver_options & | rcv_opts | |||
) |
Open a connection and receiver for `addr_url`.
Supplied receiver options will override the container's template options.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<receiver> open_receiver | ( | const std::string & | addr_url, | |
const connection_options & | conn_opts | |||
) |
Open a connection and receiver for `addr_url`.
Supplied receiver or connection options will override the container's template options.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
returned<receiver> open_receiver | ( | const std::string & | addr_url, | |
const proton::receiver_options & | rcv_opts, | |||
const connection_options & | conn_opts | |||
) |
Open a connection and receiver for `addr_url`.
Supplied receiver or connection options will override the container's template options.
Thread safety** - Container method return values are thread-unsafe*. A single-threaded application can safely assign the `returned<T>` value to a plain `T`. A multithreaded application *must* ignore the returned value because it may already be invalid by the time the function returns. Multithreaded applications can safely access the value inside messaging_handler functions.
void client_connection_options | ( | const connection_options & | conn_opts | ) |
Connection options applied to outgoing connections.
These are applied first and then overridden by any options provided in `connect()` or `messaging_handleron_connection_open()`.
connection_options client_connection_options | ( | ) | const |
Connection options applied to outgoing connections. These are applied first and then overridden by any options provided in `connect()` or `messaging_handleron_connection_open()`.
void server_connection_options | ( | const connection_options & | conn_opts | ) |
Connection options applied to incoming connections.
These are applied first and then overridden by any options provided in `listen()`, `listen_handleron_accept()`, or `messaging_handleron_connection_open()`.
connection_options server_connection_options | ( | ) | const |
Connection options applied to incoming connections. These are applied first and then overridden by any options provided in `listen()`, `listen_handleron_accept()`, or `messaging_handleron_connection_open()`.
void sender_options | ( | const class sender_options & | snd_opts | ) |
Sender options applied to senders created by this container.
They are applied before `messaging_handleron_sender_open()` and can be overridden.
class sender_options sender_options | ( | ) | const |
Sender options applied to senders created by this container. They are applied before `messaging_handleron_sender_open()` and can be overridden.
void receiver_options | ( | const class receiver_options & | rcv_opts | ) |
Receiver options applied to receivers created by this container.
They are applied before `messaging_handleron_receiver_open()` and can be overridden.
class receiver_options receiver_options | ( | ) | const |
Receiver options applied to receivers created by this container. They are applied before `messaging_handleron_receiver_open()` and can be overridden.
void schedule | ( | duration | dur, | |
work | fn | |||
) |
Schedule `fn` for execution after a duration.
The piece of work can be created from a function object.
C++ versions** - With C++11 and later, use a `stdfunction<void()>` type for the `fn` parameter.