Chapter 7. Multithreading
AMQ C++ supports full multithreading with C++11 and later. Limited multithreading is possible with older versions of C++. See Section 7.5, “Using older versions of C++”.
7.1. Threading model
container object can handle multiple connections concurrently. As AMQP events occur on connections, the container calls
messaging_handler callback functions. Callbacks for any one connection are serialized (not called concurrently), but callbacks for different connections can be safely executed in parallel.
You can assign a handler to a connection in
listen_handler::on_accept() using the
handler connection option. We recommend creating a separate handler for each connection. That way the handler does not need locks or other synchronization to protect it against concurrent use by library threads. If any non-library threads use the handler concurrently, then you will need synchronization.
7.2. Thread-safety rules
delivery objects are not thread-safe and are subject to the following rules.
You must use them only from a
messaging_handlercallback or a
- You must not use objects belonging to one connection from a callback for another connection.
- You can store AMQ C++ objects in member variables for use in a later callback, provided you respect rule two.
message object is a value type with the same threading constraints as a standard C++ built-in type. It cannot be concurrently modified.
7.3. Work queues
work_queue interface provides a safe way to communicate between different connection handlers or between non-library threads and connection handlers.
Each connection has an associated
- The work queue is thread-safe (C++11 or greater). Any thread can add work.
workitem is a
std::function, and bound arguments are called like an event callback.
When the library calls the work function, it will be serialized safely so that you can treat the work function like an event callback and safely access the handler and AMQ C++ objects stored on it.
7.4. The wake primitive
connection::wake() method allows any thread to prompt activity on a connection by triggering an
on_connection_wake() callback. This is the only thread-safe method on
wake() is a lightweight, low-level primitive for signaling between threads.
It does not carry any code or data, unlike
Multiple calls to
wake()might be coalesced into a single
on_connection_wake()can occur without any application call to
wake()since the library uses
The semantics of
wake() are similar to
std::condition_variable::notify_one(). There will be a wakeup, but there must be some shared application state to determine why the wakeup occurred and what, if anything, to do about it.
Work queues are easier to use in many instances, but
wake() may be useful if you already have your own external thread-safe queues and need an efficient way to wake a connection to check them for data.
7.5. Using older versions of C++
Before C++11 there was no standard support for threading in C++. You can use AMQ C++ with threads but with the following limitations.
The container will not create threads. It will only use the single thread that calls
None of the AMQ C++ library classes are thread-safe, including
work_queue. You need an external lock to use
containerin multiple threads. The only exception is
connection::wake(). It is thread-safe even in older C++.
work_queue APIs accept C++11 lambda functions to define units of work. If you are using a version of C++ that does not support lambdas, you must use the
make_work() function instead.