Routines

Introduction

Once SHIPBridge host is integrated into a system and able to connect to a SIM, the next task one faces is building, sending, and receiving SHIPBridge messages in order to communicate and control the SIM. Serious Integrated provides and maintains 'routines' that abstract the underlying messaging required to perform high level operations that can be run by instances of tasks called 'workers'. The routines and workers can either be used directly for performing high level SHIPBridge operations in user systems or to provide an example for how a user could do the same in their own code.

Worker

Complementing the asynchronous and multitasking nature of SIMs and the SHIPBridge protocol, the worker design enables SHIPBridge hosts to instantiate the resources needed for running one to many high level operations asynchronously.

Workers can have the following public API functions that can be directly performed on them:

• SHIP_Glue_C2R_Worker_RxControl
  • Enqueues the control message on the worker's control queue for the currently executing routine (typically used for passing additional data or stimulus to a routine).
• SHIP_Glue_C2R_Worker_Kick
  • Forces the worker to wake up and attempt to execute another step of the current routine.
• SHIP_Glue_C2R_Worker_AbortRoutine
  • Sets up the worker's SHIP_Glue_C2R_Routine to attempt to abort (gracefully only if it aborts within the supplied timeout period).
• SHIP_Glue_C2R_Worker_StartRoutine
  • Sets up the worker's SHIP_Glue_C2R_Routine if there is no routine currently in progress.
• SHIP_Glue_C2R_Worker_Start
  • Starts (and creates) the OS resources associated with the worker.
• SHIP_Glue_C2R_Worker_Stop
  • Stops (and destroys) the OS resources associated with the worker.

Other public API functions provided for working with workers are:

• SHIP_Glue_C2R_Worker_Find
  • Looks up the context data for the worker associated with the SHIPBridge_Endpoint and session ID.
• SHIP_Glue_C2R_Worker_RxMessage
  • Enqueues the SHIP_Buffer containing a SHIPBridge_Message on the appropriate worker's message queue (typically used in response servicers to route responses to correct recipient worker).

Instantiating a Worker

Creating a worker requires that you already have a pointer to a SHIP_Glue_C2R_Worker, a SHIPBridge_Endpoint, and a unique unused session ID under that SHIPBridge_Endpoint. The rest of the arguments are queue sizes, the task stack size, the task priority, and OS object names for debug purposes.

    //
    // Initialize this endpoint's session 1 routine worker.
    //
    SHIP_Glue_C2R_Worker_Start(
            &pEPC->worker,
            pEp,
            1,
            8,
            8,
            400,
            1,
            "Session1WorkerTask",
            "Session1WorkerLock",
            "Session1WorkerSignals",
            "Session1WorkerControlQueue",
            "Session1WorkerMessageQueue");

Once you have a worker started, you can now give it a routine to execute.