5. Tasking model in PolyORB

5.1. PolyORB Tasking runtimes

PolyORB may use any of three different tasking runtimes to manage and synchronize tasks, if any. Tasking runtime capabilities are defined in the Ada Reference Manual :cite:`ada-rm`.

The choice of a specific tasking runtime is a compile-time parameter, Tasking runtimes for more details on their configuration.

5.1.1. Full tasking runtime

Full tasking runtime refers to the configuration in which there are dependencies on the tasking constructs defined in chapter 9 of :cite:`ada-rm`. It makes use of all capabilities defined in this section to manage and synchronize tasks.

In this configuration, a PolyORB application must be compiled and linked with a tasking-capable Ada runtime.

5.1.2. No tasking runtime

No tasking runtime refers to the configuration in which there is no dependency on tasking constructs. Thus, no tasking is required.

In this configuration, a PolyORB application may be compiled and linked with a tasking-capable Ada runtime or a no-tasking Ada runtime.

5.1.3. Ravenscar tasking runtime

Ravenscar tasking runtime refers to the configuration in which tasking constructs are compliant with the Ravenscar tasking restricted profile.

In this configuration, a PolyORB application may be compiled and linked with a tasking-capable Ada runtime or a Ravenscar Ada runtime.

To configure tasking constructs used by PolyORB, one must instantiate the PolyORB.Setup.Tasking.Ravenscar generic package shown below to set up tasks and protected objects used by PolyORB core.

------------------------------------------------------------------------------
--                                                                          --
--                           POLYORB COMPONENTS                             --
--                                                                          --
--      P O L Y O R B . S E T U P . T A S K I N G . R A V E N S C A R       --
--                                                                          --
--                                 S p e c                                  --
--                                                                          --
--         Copyright (C) 2002-2012, Free Software Foundation, Inc.          --
--                                                                          --
-- This is free software;  you can redistribute it  and/or modify it  under --
-- terms of the  GNU General Public License as published  by the Free Soft- --
-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
-- sion.  This software is distributed in the hope  that it will be useful, --
-- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public --
-- License for  more details.                                               --
--                                                                          --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception,   --
-- version 3.1, as published by the Free Software Foundation.               --
--                                                                          --
-- You should have received a copy of the GNU General Public License and    --
-- a copy of the GCC Runtime Library Exception along with this program;     --
-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
-- <http://www.gnu.org/licenses/>.                                          --
--                                                                          --
--                  PolyORB is maintained by AdaCore                        --
--                     (email: sales@adacore.com)                           --
--                                                                          --
------------------------------------------------------------------------------

--  You should instantiate this package to set up a ravenscar profile.

with System;

with PolyORB.Tasking.Profiles.Ravenscar.Threads.Annotations;

with PolyORB.Tasking.Profiles.Ravenscar.Threads;
with PolyORB.Tasking.Profiles.Ravenscar.Mutexes;
with PolyORB.Tasking.Profiles.Ravenscar.Condition_Variables;

generic
   Number_Of_Application_Tasks    : Integer;
   --  Number of tasks created by the user.

   Number_Of_System_Tasks         : Integer;
   --  Number of tasks created by the PolyORB run-time library.

   Number_Of_Conditions           : Integer;
   --  Number of preallocated conditions.

   Number_Of_Mutexes              : Integer;
   --  Number of preallocated mutexes.

   Task_Priority                  : System.Priority;
   --  Priority of the tasks of the pool.

   Storage_Size                   : Natural;
   --  Stack size of the system tasks.

package PolyORB.Setup.Tasking.Ravenscar is

   package Threads_Package is
      new PolyORB.Tasking.Profiles.Ravenscar.Threads
     (Number_Of_Application_Tasks,
      Number_Of_System_Tasks,
      Task_Priority,
      Storage_Size);

   package Thread_Annotations_Package is new Threads_Package.Annotations;

   package Conditions_Package is
      new PolyORB.Tasking.Profiles.Ravenscar.Condition_Variables
     (Threads_Package,
      Number_Of_Conditions);

   package Mutexes_Package is
      new PolyORB.Tasking.Profiles.Ravenscar.Mutexes
     (Threads_Package,
      Number_Of_Mutexes);

end PolyORB.Setup.Tasking.Ravenscar;

5.2. PolyORB ORB Tasking policies

PolyORB ORB Tasking policies control the creation of tasks to process all middleware internal jobs, e.g. request processing, I/O monitoring.

Note: there is a dependency between ORB Tasking policies, and the runtime used, as detailed below.

5.2.1. No Tasking

Under the No Tasking ORB policy, no tasks are created within the middleware instance: it uses the environment task to process all jobs. Note that this policy is not thread safe and is compatible with the No tasking runtime only.

5.2.2. Thread Pool

Under the Thread Pool ORB policy, the middleware creates a pool of threads during initialization of PolyORB. This pool processes all jobs. The number of tasks in the thread pool can be configured by three parameters in the [tasking] configuration section.

  • min_spare_threads indicates the number of tasks created at startup.
  • max_spare_threads is a ceiling. When a remote subprogram call is completed, its anonymous task is deallocated if the number of unused tasks already in the pool is greater than the ceiling. If not, then the task is queued in the pool.
  • max_threads indicates the maximum number of tasks in the pool.

PolyORB Tasking configuration, for more information on how to configure the number of tasks in the thread pool.

5.2.3. Thread Per Session

Under the Thread Per Session ORB policy, the middleware creates one task when a new session (one active connection) is opened. The task terminates when the session is closed.

5.2.4. Thread Per Request

Under the Thread Per Request ORB policy, the middleware creates one task per incoming request. The task terminates when the request is completed.

5.3. PolyORB Tasking configuration

The following parameters allow the user to set up some of the tasking parameters.

###############################################################################
# Parameters for tasking
#

[tasking]
# Default storage size for all threads spawned by PolyORB
#storage_size=262144

# Number of threads by Thread Pool tasking policy
#min_spare_threads=4
#max_spare_threads=4
#max_threads=4

5.4. PolyORB ORB Controller policies

The PolyORB ORB Controller policies are responsible for the management of the global state of the middleware: they assign middleware internal jobs, or I/Os monitoring to middleware tasks.

ORB Controller policies grant access to middleware internals and affect one action for each middleware task. They ensure that all tasks work concurrently in a thread-safe manner.

5.4.1. No Tasking

The No Tasking ORB Controller policy is dedicated to no-tasking middleware configurations; the middleware task executes the following loop: process internal jobs, then monitor I/Os.

5.4.2. Workers

The Workers ORB Controller policy is a simple controller policy: all tasks are equal, they may alternatively and randomly process requests or wait for I/O sources.

Note: this is the default configuration provided by PolyORB sample setup files, :ref:`Sample_files.`

5.4.3. Half Sync/Half Async

The Half Sync/Half Async ORB Controller policy implements the “Half Sync/Half Async” design pattern: it discriminates between one thread dedicated to I/O monitoring that queue middleware jobs; another pool of threads dequeue jobs and process them.

Note: this pattern is well-suited to process computation-intensive requests.

5.4.4. Leader/Followers

The Leader/Followers ORB Controller policy implements the ‘Leader/Followers ‘ design pattern: multiple tasks take turns to monitor I/O sources and then process requests that occur on the event sources.

Note: this pattern is adapted to process a lot of light requests.

5.5. PolyORB ORB Controller configuration

The following parameters allow the user to set up parameters for ORB Controllers.

###############################################################################
# Parameters for ORB Controllers
#

[orb_controller]
# Interval between two polling actions on one monitor
#polyorb.orb_controller.polling_interval=0

# Timeout when polling on one monitor
#polyorb.orb_controller.polling_timeout=0