Qpid Proton C++ API  0.37.0
container

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. More...
 
 container (messaging_handler &handler)
 Create a container with a global handler for messaging events. More...
 
 container (const std::string &id)
 Create a container. More...
 
 container ()
 Create a container. More...
 
 ~container ()
 Destroy a container. More...
 
returned< connectionconnect (const std::string &conn_url, const connection_options &conn_opts)
 Connect to conn_url and send an open request to the remote peer. More...
 
returned< connectionconnect (const std::string &conn_url)
 Connect using the default Connection Configuration file. More...
 
returned< connectionconnect ()
 Connect using the default Connection Configuration file. More...
 
listener listen (const std::string &listen_url, listen_handler &handler)
 Listen for new connections on listen_url. More...
 
listener listen (const std::string &listen_url, const connection_options &conn_opts)
 Listen for new connections on listen_url. More...
 
listener listen (const std::string &listen_url)
 Listen for new connections on listen_url. More...
 
void run ()
 Run the container in the current thread. More...
 
void run (int count)
 Run the container with a pool of count threads, including the current thread. More...
 
void auto_stop (bool enabled)
 Enable or disable automatic container stop. More...
 
void stop (const error_condition &err)
 Stop the container with error condition err. More...
 
void stop ()
 Stop the container with an empty error condition. More...
 
returned< senderopen_sender (const std::string &addr_url)
 Open a connection and sender for addr_url. More...
 
returned< senderopen_sender (const std::string &addr_url, const proton::sender_options &snd_opts)
 Open a connection and sender for addr_url. More...
 
returned< senderopen_sender (const std::string &addr_url, const connection_options &conn_opts)
 Open a connection and sender for addr_url. More...
 
returned< senderopen_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. More...
 
returned< receiveropen_receiver (const std::string &addr_url)
 Open a connection and receiver for addr_url. More...
 
returned< receiveropen_receiver (const std::string &addr_url, const proton::receiver_options &rcv_opts)
 Open a connection and receiver for addr_url. More...
 
returned< receiveropen_receiver (const std::string &addr_url, const connection_options &conn_opts)
 Open a connection and receiver for addr_url. More...
 
returned< receiveropen_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. More...
 
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. More...
 
connection_options client_connection_options () const
 Connection options applied to outgoing connections. More...
 
void server_connection_options (const connection_options &conn_opts)
 Connection options applied to incoming connections. More...
 
connection_options server_connection_options () const
 Connection options applied to incoming connections. More...
 
void sender_options (const class sender_options &snd_opts)
 Sender options applied to senders created by this container. More...
 
class sender_options sender_options () const
 Sender options applied to senders created by this container. More...
 
void receiver_options (const class receiver_options &rcv_opts)
 Receiver options applied to receivers created by this container. More...
 
class receiver_options receiver_options () const
 Receiver options applied to receivers created by this container. More...
 
void schedule (duration dur, work fn)
 Schedule fn for execution after a duration. More...
 
void schedule (duration dur, void_function0 &fn)
 Deprecated - Use container::schedule(duration, work).
 

Detailed Description

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.

Examples
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.

Constructor & Destructor Documentation

◆ container() [1/4]

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 Multithreading.

Parameters
handlerglobal handler, called for events on all connections managed by the container.
idsets the container's unique identity.

◆ container() [2/4]

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 Multithreading.

Parameters
handlerglobal handler, called for events on all connections managed by the container.

◆ container() [3/4]

container ( const std::string &  id)

Create a container.

Parameters
idsets the container's unique identity.

◆ container() [4/4]

container ( )

Create a container.

This will create a default random identity

◆ ~container()

~container ( )

Destroy a container.

A container must not be destroyed while a call to run() is in progress, in particular it must not be destroyed from a messaging_handler callback.

Thread safety - in a multi-threaded application, run() must return in all threads that call it before destroying the container.

Member Function Documentation

◆ connect() [1/3]

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_handler::on_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.

Examples
helloworld.cpp, multithreaded_client.cpp, server.cpp, and service_bus.cpp.

◆ connect() [2/3]

returned<connection> connect ( const std::string &  conn_url)

Connect using the default Connection Configuration file.

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.

◆ connect() [3/3]

returned<connection> connect ( )

Connect using the default Connection Configuration file.

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.

◆ listen() [1/3]

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.

Examples
broker.cpp, direct_recv.cpp, direct_send.cpp, and server_direct.cpp.

◆ listen() [2/3]

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 Multithreading

◆ listen() [3/3]

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&);

◆ run() [1/2]

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).

Examples
broker.cpp, client.cpp, direct_recv.cpp, direct_send.cpp, helloworld.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.

◆ run() [2/2]

void run ( int  count)

Run the container with a pool of count threads, including the current thread.

C++ versions - Available with C++11 or later.

The call returns when the container stops. See auto_stop() and stop().

◆ auto_stop()

void auto_stop ( bool  enabled)

Enable or disable automatic container stop.

It is enabled by default.

If true, the container stops when all active connections and listeners are closed. If false, the container keeps running until stop() is called.

◆ stop() [1/2]

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.

When the process is complete, run() returns in all threads.

Thread safety - It is safe to call this method in any thread.

◆ stop() [2/2]

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_sender() [1/4]

returned<sender> open_sender ( const std::string &  addr_url)

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.

Examples
client.cpp, multithreaded_client_flow_control.cpp, scheduled_send.cpp, scheduled_send_03.cpp, service_bus.cpp, and simple_send.cpp.

◆ open_sender() [2/4]

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.

◆ open_sender() [3/4]

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.

◆ open_sender() [4/4]

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_receiver() [1/4]

returned<receiver> open_receiver ( const std::string &  addr_url)

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.

Examples
multithreaded_client_flow_control.cpp, and simple_recv.cpp.

◆ open_receiver() [2/4]

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.

◆ open_receiver() [3/4]

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.

◆ open_receiver() [4/4]

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.

◆ client_connection_options() [1/2]

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_handler::on_connection_open().

◆ client_connection_options() [2/2]

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_handler::on_connection_open().

◆ server_connection_options() [1/2]

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_handler::on_accept(), or messaging_handler::on_connection_open().

◆ server_connection_options() [2/2]

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_handler::on_accept(), or messaging_handler::on_connection_open().

◆ sender_options() [1/2]

void sender_options ( const class sender_options snd_opts)

Sender options applied to senders created by this container.

They are applied before messaging_handler::on_sender_open() and can be overridden.

◆ sender_options() [2/2]

class sender_options sender_options ( ) const

Sender options applied to senders created by this container.

They are applied before messaging_handler::on_sender_open() and can be overridden.

◆ receiver_options() [1/2]

void receiver_options ( const class receiver_options rcv_opts)

Receiver options applied to receivers created by this container.

They are applied before messaging_handler::on_receiver_open() and can be overridden.

◆ receiver_options() [2/2]

Receiver options applied to receivers created by this container.

They are applied before messaging_handler::on_receiver_open() and can be overridden.

◆ schedule()

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 std::function<void()> type for the fn parameter.

Examples
scheduled_send.cpp.

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