A.9     Predeclared Runtime Services

(1)   Two sets of runtime services are predeclared.  The first set declares service subprograms that can be called by the application source text directly.  The second set declares service subprograms that are intended to be called by an AADL runtime executive that can be generated from an AADL model, thus is not expected to be used directly by application component developers.

(2)   Application Runtime Services

(3)   A Send_Output runtime service allows the source text of a thread to explicitly cause events, event data, or data to be transmitted through outgoing ports to receiver ports.  The Send_Output service takes a port list parameter that specifies for which ports the transmission is initiated. The send on all ports is considered to occur logically simultaneously.  Send_Output is a non-blocking service.  An exception is raised if the send fails with exception codes indicating the failing port and type of failure.

    subprogram Send_Output
    features
      OutputPorts: in parameter <implementation-dependent port list>;
      -- List of ports whose output is transferred
      SendException: out event data; -- exception if send fails to complete
    end Send_Output;

NOTES: The Send_Output runtime service replaces the Raise_Event service  in the original AADL standard

(4)   A Put_Value runtime service allows the source text of a thread to supply a data value to a port variable.  This data value will be transmitted at the next Send_Output call in the source text or by the runtime system at completion time or deadline.

    subprogram Put_Value
    features
      Portvariable: requires data access; -- reference to port variable
      DataValue: in parameter; -- value to be stored
      DataSize: in parameter;  - size in bytes (optional)
    end Put_Value;

(5)   A Receive_Input runtime service allows the source text of a thread to explicitly request port input on its incoming ports to be frozen and made accessible through the port variables.  Any previous content of the port variable is overwritten, i.e., any previous queue content not processed by Next_Value calls is discarded.  The Receive_Input service takes a parameter that specifies for which ports the input is frozen.  Newly arriving data may be queued, but does not affect the input that thread has access to (see Section 9.1).  Receive_Input is a non-blocking service.

    subprogram Receive_Input
    features
      InputPorts: in parameter <implementation-dependent port list>;
      -- List of ports whose input is frozen
    end Receive_Input;

(6)   In the case of data ports the value is made available without requiring a Next_Value call.  The Get_Count will return the value 1 if the value has been updated, i.e., is fresh.  If the data is not fresh, the value zero is returned.

(7)   In the case of event data ports each data value is retrieved from the queue through the Next_Value call and made available as port variable value.  Subsequent calls to Get_Value or direct access of the port variable will return this value until the next Next_Value call.

(8)   In case of event ports and event data ports the queue is available to the thread, i.e., Get_Count will return the size of the queue.  If the queue size is greater than one the Dequeued_Items property and Dequeue_Protocol property may specify that more than one element is made accessible to the source text of a thread.

(9)   A Get_Value runtime service shall be provided that allows the source text of a thread to access the current value of a port variable.  The service call returns the data value.  Repeated calls to Get_Value result in the same value to be returned, unless the current value is updated through a Receive_Input call or a Next_Value call.

    subprogram Get_Value
    features
      Portvariable: requires data access; -- reference to port variable
      DataValue: out parameter; -- value being retrieved
      DataSize: in parameter;  - size in bytes (optional)
    end Get_Value;

(10)  A Get_Count runtime service shall be provided that allows the source text of a thread to determine whether a new data value is available on a port variable, and in case of queued event and event data ports, who many elements are available to the thread in the queue. A count of zero indicates that no new data value is available.

    subprogram Get_Count
    features
      Portvariable: requires data access; -- reference to port variable
      CountValue: out parameter BaseTypes::Integer; -- content count of port variable
    end Get_Count;

(11)  A Next_Value runtime service shall be provided that allows the source text of a thread to get access to the next queued element of a port variable as the current value. A NoValue exception is raised if no more values are available.

    subprogram Next_Value
    features
      Portvariable: requires data access; -- reference to port variable
      DataValue: out parameter; -- value being retrieved
      DataSize: in parameter;  -- size in bytes (optional)
      NoValue: out event port; -- exception if no value is available
    end Next_Value;

(12)  A Updated runtime service shall be provided that allows the source text of a thread to determine whether input has been transmitted to a port since the last Receive_Input service call.

    subprogram Updated
    features
      Portvariable: in parameter <implementation-dependent port reference>;
      -- reference to port variable
      FreshFlag: out parameter BaseTypes::Boolean; -- true if new arrivals 
    end Updated;

(13)   Runtime Executive Services

(14)  The following are subprograms may be explicitly called by application source code, or they may be called by an AADL runtime system that is generated from an AADL model.

(15)  The Get_Resource and Release_Resource  runtime services represent an abstract interface for functions that perform locking and unlocking of resources according to the specified concurrency control protocol.  The method may lock multiple resources simultaneously.

    subprogram  Get_Resource
    features
      resource: in parameter <implementation-specific representation of one or more resources>; 
    end Get_Resource;
    subprogram  Release_Resource 
    features
      resource: in parameter <implementation-specific representation of one or more resources>; 
    end Release_Resource;

(16)  The Await_Dispatch  runtime service is called to suspend the thread execution at completion of its dispatch execution.  It is the point at which the next dispatch resumes. The service call takes several parameters.  It takes a DispatchPort list and an optional trigger condition function to identify the ports and the condition under which the dispatch is triggered.  If the condition function is not present any of the ports in the list can trigger the dispatch.  It takes a DispatchedPort as out parameter to return the port(s) that triggered the dispatch.  It takes OutputPorts and InputPorts as port lists.  OutputPorts, if present, identifies the set of ports whose sending is initiated at completion of execution, equivalent to an implicit Send_Output service call. InputPorts, if present, identifies the set of ports whose content is received at the next dispatch, equivalent to an implicit Receive_Input service call. 

    subprogram  Await_Dispatch 
    features
-- List of ports whose output is sent at completion/deadline
      OutputPorts: in parameter <implementation-defined port list>;
      -- List of ports that can trigger a dispatch
      DispatchPorts: in parameter <implementation-defined port list>; 
      -- list of ports that did trigger a dispatch
      DispatchedPort: out parameter < implementation-defined port list>;
      -- optional function as dispatch guard, takes port list as parameter 
      DispatchConditionFunction: requires subprogram access;
      -- List of ports whose input is received at dispatch
      InputPorts: in parameter <implementation-defined port list>; 
    end Await_Dispatch;

(17)  A Raise_Error runtime service shall be provided that allows a thread to explicitly raise a thread recoverable or thread unrecoverable error.  Raise_Error takes an error type identifier as parameter.

    subprogram  Raise_Error 
    features
      errorID: in parameter <implementation-defined error type>;
    end Raise_Error;

(18)  A Get_Error_Code runtime service shall be provided that allows a recover entrypoint to determine the type of error that caused the entrypoint to be invoked.

    subprogram Get_Error_Code 
    features
      errorID: out parameter <implementation-defined error type>; 
    end Get_Error_Code;

(19)  Subprograms have event ports but do not have an error port. If a Raise_Error is called, it is passed to the error port of the enclosing thread.  If a Raise_Error is called by a remotely called subprogram, the error is passed to the error port of the thread executing the remotely called subprogram.  The Raise_Error method is permitted to have an error identification as parameter value. This error identification can be passed through the error port as the data value, since the error port is defined as event data port.

(20)  A Await_Result runtime service shall be provided that allows an application to wait for the result of a semi-synchronous subprogram call. 

    subprogram Await_Result 
    features
      CallID: in parameter <implementation-defined call ID>; 
    end Await_Result;

(21)  Current_System_Mode returns a value corresponding to the active system operation mode (SOM).

    subprogram Current_System_Mode
    features
      ModeID: out parameter <implementor-specific>; -- ID of the mode
    end Current_System_Mode;

(22)  Set_System_Mode indicates the next SOM the runtime system must switch to.  System modes are assumed to have identifying numbers.

    subprogram Set_System_Mode
    features
      ModeID: in parameter <implementor-specific>; -- ID of the SOM
    end Set_System_Mode;

(23)  Current_System_Mode returns a value corresponding to the active system operation mode (SOM).

    subprogram Current_System_Mode
    features
      ModeID: out parameter <implementor-specific>; -- ID of the mode
    end Current_System_Mode;

(24)  Set_System_Mode indicates the next SOM the runtime system must switch to.  System modes are assumed to have identifying numbers.

    subprogram Set_System_Mode
    features
      ModeID: in parameter <implementor-specific>; -- ID of the SOM
    end Set_System_Mode;

(25)  The following subprograms take a process, virtual processor, or processor ID as parameter.  The ID representation is determined by the runtime system.

(26)  Stop_Process is called for a controlled shut-down of a process, i.e., all of its contained threads, whether executing, awaiting a dispatch, or not part of the current mode, are given a chance to execute their finalize entrypoint before being halted.

(27)  Abort_Process is called for a shut-down of a process due to an anomaly.  All of its contained threads are terminated immediately.

(28)  Stop_Virtual_Processor is called to initiate a transition to the virtual processor stopping state at the next hyperperiod. This has the effect of initiating Stop_Virtual_Processor for all virtual processors bound to the virtual processor, and Stop_Process for all processes bound to the virtual processor.

(29)  Abort_Virtual_Processor  is called for a shut-down of a virtual processor due to an anomaly.  All virtual processors and processes bound to the virtual processor are aborted.

(30)  Stop_Processor is called to initiate a transition to the processor stopping state at the next hyperperiod. This has the effect of initiating Stop_Virtual_Processor for all virtual processors bound to the processor, and Stop_Process for all processes bound to the processor.

(31)  Abort_Processor  is called for a shut-down of a processor due to an anomaly.  All virtual processors and processes bound to the processor are aborted.

(32)  Stop_System is called to initiate a transition to the system stopping state, which will initiate a Stop_Processor for all processors in the system.

(33)  Abort_System is called for a shut-down of the system due to an anomaly.  All processors in the system are aborted.