Page History

...

• Goals:
  • Minimise the number of locks
  • Define the correct locking order
  • Document what application behaviour is legal (e.g. what can be done inside MessageListener.onMessage?)
  • Make the JMS client thread-safe when used legally.

Threads fall into two three categories:

1. Application threads using the JMS API. Only use the top half of the Proton API.
2. One or more driver threads for I/O. Managed by the JMS client. Only use the bottom half of the Proton API.
3. Threads managed by the JMS client that call application code (e.g. MessageListener.onMessage, ExceptionListener.onException and CompletionListener.xxx).

For a given connection:

1. State shared by multiple application threads (namely the state of the objects in the JMS layer) is guarded by the JMS ConnectionLock.
2. State shared by the application and driver threads is guarded by the AmqpConnection lock. This shared state is:
   1. A small number of flags the application and driver threads use to indicate to each other that "something has changed".
   2. The Proton objects. This sharing occurs inside Proton but needs to be guarded by the JMS client because Proton itself is not thread-safe.

TODO extend the locking scheme to include the JMS Client-owned threads that call application code.

Synchronous operations must follow the locking scheme indicated by the following pseudo-code:

...