ConnectSMB Asynchronous Programming Model

This section is intended for those contributing to the ConnectSMB stack, or developing applications that leverage the internal APIs of the ConnectSMB stack. If you are simply integrating the stack with an application, you need not be concerned with this section.

The two main components that provide the async programming model are the ConnectSMB Scheduler and the ConnectSMB Application Manager. These two components utilize a collection of eventing APIs available to the Treading model as well.

There can be one or more schedulers. A scheduler is a run-loop that dispatches events. Each run loop is a platform thread.
Although everything can run in a single run-loop, there may be a desire to leverage some QoS on platform threads, or there may be a desire to distribute run-loops onto each processor of an SMP system.

At application load time or any time else in the life of an application, an async handler (or we call them 'applets' or 'apps') can be created and added to a scheduler. Each app has a callback template that declares some app secific info as well as dispatch routines for initializing, syncing of events, processing of events, and destroying.

The 'syncing of events' we call 'preselect'. When an app is created and after every time the app has handled an event, the preselect routine is called. The preselect routine typically dispaches on state and determines what events are waitable. These events are then registered with the scheduler. There are all sorts of waitable events (see Waitable Events).

When an event fires, the postselect routine is called with the event that fired. Based on the event and app state, the postselect routine can perform whatever processing is required, change state or remain, create new events, signal other events. As it leaves the postselect routine, the updated waitable events are communicated to the scheduler.

Apps have another callback where it can destroy itself and notify any waiters on it's app destruction.

You can view the test apps distributed as part of of_core for examples of using the concurrency models.

• Datagram Test App
• Event Test App
• File Test App
• Path Test App
• Stream Test App
• Thread Test App
• Timer Test App
• WaitQ Test App

Because of the fact that apps are executed on the run-loop, if an application developer can insure that there is only one app loop, or ensure that the application context is local to the particular scheduler, then the callbacks are completely thread-safe so no locking/synchronization is required.

Waitable Events

A waitable event is one that can be provided to an Async scheduler for an async app, can be added to a waitset and waited on as part of the group, or can be individually waited on.

The following events are waitable:

• Wait Queue
• File Open Files File APIs
• Network Socket
• Buffer Open Files File APIs
• Event (semaphore)
• Timer