/*!\mainpage Framework API for Multithreading Task and Protocol State Machine\author Yoshihiro Ohba\date Created: December 1, 2003\date Updated: January 10, 2004\section IntroductionThis framework API provides a general way to implement communicationprotocols in multithreading environments.  The API contains threesub-APIs, i.e., job sub-API, task sub API and state machine sub-API.The job sub-API defines a generic processing element that can be usedfor any purpose.The task sub-API provides the functionality to execute jobs in amultithreading environment.The state machine sub-API provides the functionality to define andexecute state machines of any types.Any protocol implementation in Open Diameter should be written byusing this framework API in order to reduce development time andimprove manageability of the entire source tree.\section tagJob Job Sub-APIA job is an object that has an operation to execute.  The operationcan be executed by any entity including a task (\ref tagTask) or someother job).  AAA_Job is the base class for any job and provides thefollowing basic methods:- <b>Serve</b> method.  The operation that is executed by an executing entity.- <b>Schedule</b> method.  This method is used for requesting a jobexecuting entity to schedule the job so that the Serve() method willbe called by the entity.- <b>ExistBacklog</b> method.  This method indicates whether thereis any outstanding operation for this job.- <b>BacklogSize</b> method.  This method indicates the current numberof outstanding operations for this job.- <b>Name</b> method.  This method is used for setting or getting thename of the job.- <b>Data</b> method.  This method is used for setting or getting thedata of the job.- <b>Priority</b> method.  This method is used for setting or gettingthe priority of the job.  The priority is used for scheduling the job.- <b>Weight</b> method.  This method is used for setting or gettingthe weight of the job.  The weight is used for scheduling the job.\subsection tagQueueJob Queue JobA queue job is a job that has a queue to store entries of any type.The type of entries stored in the queue is specified as templateparameter.  The framework API defines two queue entry types asbuilt-in types, job and event, that are used by AAA_GroupedJob andAAA_StateMachineWithTask classes.  The queue job class supports FIFO,WFQ (Weighted Fair Queueing) and priority queueing disciplines byusing the two parameters "priority" and "weight".  An entry withhigher priority is always dequeued earlier than an entry with lowerpriority.  Among the entries with the same priority, an entry withhigher weight has a greater chance to be dequeued thatn an entry withlower weight.  The AAA_QueueJob class has the following methods inaddition to the methods derived from AAA_Job:- <b>Enqueue</b> method.  This method is used for storing an event tothe event queue.  Both blocking and non-blocking enqueue operationsare supported.- <b>Dequeue</b> method.  This method is used for obtaining an eventfrom the event queue.  Both blocking and non-blocking dequeueoperations are supported.- <b>Flush</b> method.  This method is used for flushing the eventqueue.- <b>Remove</b> method.  This method is used for removing a specifiedentry from the event queue.  In the case where multiple copies of thesame entry is enqueued, the all copies are removed.- <b>MaxSize</b> method.  This method is used for obtaining the maximumqueue size in the number of entries.\subsection tagGroupedJob Grouped JobA grouped job is a queue job that has a queue to store other jobs andhas a parent job for which it requests scheduling on behalf of otherjobs.  The grouped job is used for constucting a job hierarchy.AAA_SchedulingPolicy parameter is used for specifying the jobscheduling discipline.  The grouped job is used for job serializationand job scheduling.\subsection tagJobHandle Job HandleA job handle provides a safe way to deallocate memory for job objects,where memory deallocation can occur even in the constuctor of anobject of a class that creats a job.  When the handle is deleted, thehandle calls AAA_JobDeleter() function which performs a deleteoperation with treating the job as a shared object (i.e., if the jobis not deleted until the job is not owned by any objects.).\subsection tagQueueJob Queue Job\section tagTask Task Sub-APIA task is an active object that generates threads for executing joboperations.  It consists of one thread (referred to as the timerthread) that handles timer events and one or more thread (eachreferred to as a job serving thread) that execute job operations.  Atask has a root job for which Serve() method is called by the jobserving threads.  AAA_Task provides the following basic methods:- <b>Start</b> method.  This method is used for starting the task.- <b>Stop</b> method.  This method is used for stopping the task.Jobs are not allowed to enter the task storage. Jobs that have beenalready entered in the task storage will be served.- <b>ScheduleTimer</b> method.  This method is used for scheduling atimer event.  The timer event will be served by the timer thread.- <b>CancelTimer</b> method.  This method is used for canceling atimer event that has been scheduled by ScheduleTimer method.\image html task-1.gif "Figure 1: AAA_Task"\section tagStateMachine State Machine Sub-APIA state machine is a general component to implement arbitrarycommunication protocols.  A state machine consists of a statetransition table and a set of state variables.\subsection tagStateTable State TableA state transition table (or simply a state table in this document)defines the behavior of the target protocol.  Each entry of a statetable is defined as AAA_StateTableEntry and has the followingattributes:- <b>Current State</b> A 32-bit unsigned integer that represents thestate where the state machine stayed immediately before receiving the event.- <b>Event</b> A 32-bit unsigned integer that represents an event the state machine is allowed to receive in the current state.- <b>Next State</b>  A 32-bit unsigned integer that represents thenext state to which the state machine moves after receiving the event.- <b>Action</b> A functor that contains the operation performed whenthe state machine accepts the event.  An action can take a singleargument of arbitrary type.  Action is defined as a template classAAA_Action.  An example action class definition is shown below.\code/// Action class for EAP. class EapAction : public AAA_Action<EapSession>{ public:  virtual void operator()(EapSession&) {} protected:  EapAction() {}  virtual ~EapAction() {}};\endcode- <b>isWildcardEvent</b> A boolean variable that indicates whether theentry accepts any event.In addition, one of the Current State values in the state table ischosen as the <b>Initial State</b> where the state machine starts itsoperation.The base class for state table is AAA_StateTable.State machines objects of the same class should share the same statetable objects to save the memory resources.  For this purpose, it isbetter to define state table classes as singletons.Figure 2 shows an example state table.  An event "*" indicates anwildcard event which matches any event.  An action "null action"indicates an action that performs no operation.\image html statemachine-1.gif "Figure 2: State Table"AAA_StateTable class provides the following methods for tablemanipuration:- <b>AddStateTableEntry</b> method.  This method is used for adding astate table entry with a specific event.- <b>AddWildcardStateTableEntry</b> method.  This method is used foradding a state table entry with a wildcard event.- <b>InitialState</b> method.  This method is used for setting andgetting the initial state.- <b>FindStateTableEntry</b> method.  This method is used for findinga state table entry that matches a particular current state and anevent.\subsection tagStateMachine State MachineA state machine has the following basic methods:- <b>Start</b> method.  This method is used for starting the state machine.- <b>Stop</b> method.  This method is used for stopping the state machine.- <b>Restart</b> method.  This method is used for restarting the state machine.- <b>Running</b> method.  This method indicates whether the state machine has been started and not been stopped.- <b>Event</b> method.  This method is used for passing event to thestate machine.  Within this method, the state table is looked up andthe action corresponding to the current state and the received eventwill be executed.The base state machine class is defined as AAA_StateMachineBase.Other state machine classes are derived from the base class anddefined as template class in which the action argument type is used asthe template parameter.  The base class of templated state machine isAAA_StateMachine<ARG>.\subsection tagStateMachineWithTimer State Machine With Timer HandlingA state machine with timer is a state machine that is capable ofgenerating and deleting timer events.  Timer events generated by the astate machine with timer will be bound to an ACE_Reactor, which istypically a reactor created by the timer thread in a task (\reftagTask).Timer events are categorized into timer types (the default timer typeis zero(0)).  The state machine stores at most one timer event foreach timer type.  A unique timer type is allocated by using timer typeallocator (defined in AAA_TimerTypeAllocator_S andAAA_TimerTypeAllocator classes).The AAA_StateMachineWithTimer<ARG> is the base class for state machinewith timer and provides the following methods:- <b>ScheduleTimer</b> method.  This method is used for scheduling atimer event.- <b>CancelTimer</b> method.  This method is used for scheduling atimer event.A sample program that uses the framework API is shown below.\include diameter_eap_server_fsm.hxx\include diameter_eap_server_fsm.cxx\include server_test.cxx*/