Creating Contexts
Contexts are used for organizing communications between applications and a Solace PubSub+ event broker. Each client application must use a minimum of one Context. A Context acts as a container in which one or more Sessions can be configured and Session‑related events can be handled. It encapsulates threads that drive network I/O and message delivery notification for the Sessions and Session components associated with that Context.
Context properties are used to dictate the behavior of a Context. If no specific Context properties are specified, the default values are used. For information on the Context properties refer to the API Developer Online Reference documentation for the appropriate messaging API.
Callbacks and Delegates
When using the C or .NET APIs, all callbacks or delegate invocations (for example, message receive callbacks, event callback, and timer callbacks) from the API to the application run from the Context thread. For optimal performance, the following rules should be followed when developing your applications for use with Solace PubSub+
- The Context thread must run to detect relief from flow control and unblock waiting application threads.
- The Context thread must run to complete the Session connection sequence and unblock applications waiting for the connection to complete.
- The Context thread must run to unblock applications waiting for confirmation of subscription requests.
Consequently, applications must not block in callback/delegate routines because it can deadlock the application or at a minimum severely degrade receive performance. Deferring SolClient processing by running for excessively long periods of time in the callback routines prevents the API from unblocking other application threads that might be waiting for confirmation of sent messages, or be blocked in flow-control situations.
To create a Context, call a method or function listed below appropriate for the messaging API. Once created, a Context is automatically started.
JCSMP
A default Context is created by the messaging API implicitly; however, it also provides the ability to create new Contexts.
C API
This is the only Messaging API that allows client applications to ‘drive’ the Context’s main loop using their own application threads.
| PubSub+ Messaging API | Use |
|---|---|
|
JCSMP |
JCSMPFactory.createContext(...) |
|
Java RTO |
Solclient.createContextForHandle(...) |
|
C |
solClient_context_create(...) |
|
.NET |
ContextFactory.CreateContext(...) |
|
JavaScript and Node.js |
Not applicable |
Related Samples
For an example of how to create a Context for the Java RTO, C, and .NET APIs, refer to the DirectPubSub sample.
| PubSub+ Messaging API | Use |
|---|---|
|
JCSMP |
Context.destroy() |
|
Java RTO |
ContextHandle.destroy() |
|
C |
solClient_context_destroy(...) |
|
.NET |
IContext.Dispose() |
|
JavaScript and Node.js |
Not applicable |
Context Timers
When using the C or .NET APIs, Contexts can use a timer to perform a scheduled task. These tasks are guaranteed to execute on the thread driving the Context with which the timer tasks are registered.
The Context timer relies on a defined callback or delegate, which allows a callback routine to be invoked within the Context’s thread when a set interval of time expires. A repeating or a one-shot (that is, one-time) callback/delegate can be used. For example, a timer could be used to publish messages at set intervals or to perform an asynchronous operation just once.
To start a Context timer, call a function or method listed below. You must pass in the type of timer to start (one-shot or repeat), the requested timer duration (in milliseconds), and the callback routine or delegate to invoke when the timer expires.
When the timer expires, the specified timer callback routine is invoked. If it is a repeat timer, the timer is automatically rescheduled for the same duration, and it continues to run until the timer is stopped. If it is a one-shot timer, the timer is automatically canceled.
| PubSub+ Messaging API | Use |
|---|---|
|
JCSMP |
Not applicable |
|
Java RTO |
Not applicable |
|
C |
solClient_context_startTimer(...) |
|
.NET |
TimerTask.Start(...) |
|
JavaScript and Node.js |
Not applicable |
Contexts, Sessions, Flows, or timers cannot be disposed in a callback.
Related Samples
For an example of how to create a Context timer for the C API, refer to the dtoPubSub sample.