FW Profile - C1 Implementation
FwPrSCreate.h File Reference

Declaration of the static creation interface for a FW Procedure. More...

Go to the source code of this file.

Macros

#define FW_PR_INST(PR_DESC, N, NDEC, NFLOWS, NA, NG)
 Instantiate a procedure descriptor and its internal data structure. More...
 
#define FW_PR_INST_NODEC(PR_DESC, N, NFLOWS, NA, NG)
 Instantiate a procedure descriptor and its internal data structure. More...
 
#define FW_PR_INST_DER(PR_DESC, NA, NG)
 Instantiate a descriptor for a derived procedure. More...
 

Functions

void FwPrInit (FwPrDesc_t prDesc)
 Initialize a procedure descriptor to represent an unconfigured procedure with no control flows, no actions, and no guards. More...
 
void FwPrInitDer (FwPrDesc_t prDesc, FwPrDesc_t prDescBase)
 Initialize a procedure descriptor to extend another procedure (the base procedure). More...
 

Detailed Description

Declaration of the static creation interface for a FW Procedure.

A FW Procedure is described by a procedure descriptor. This interface allows a procedure descriptor to be created statically (i.e. without using dynamic memory allocation). In this sense, this interface is alternative to the dynamic creation interface defined in FwPrDCreate.h.

A procedure can be created in two ways:

  • It can be created from scratch, or
  • It can be created by extending an existing procedure.

In both cases, creation of a procedure descriptor is done in two steps:

  • The procedure descriptor and its internal data structures are instantiated.
  • The procedure descriptor and its internal data structures are initialized.

Instantiation is done by means of the following macros.

  • FW_PR_INST should be used to instantiate from scratch a descriptor for a procedure with one or more choice pseudo-states.
  • FW_PR_INST_NODEC should be used to instantiate from scratch a descriptor for a procedure with no choice pseudo-states.
  • FW_PR_INST_DER should be used to instantiate a descriptor for a procedure which is derived by extending another procedure.

Initialization is done by means of the following functions:

  • FwPrInit should be used to initialize a descriptor which has been created from scratch with either FW_PR_INST or FW_PR_INST_NODEC.
  • FwPrInitDer should be used to initialize a descriptor of a procedure which is derived by extending another procedure

After a procedure descriptor has been instantiated and initialized, it will normally need to be configured. Configuration of a procedure descriptor can be done using the functions described in the FwPrConfig.h file.

Author
Vaclav Cechticky vacla.nosp@m.v.ce.nosp@m.chtic.nosp@m.ky@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m
Alessandro Pasetti paset.nosp@m.ti@p.nosp@m.np-so.nosp@m.ftwa.nosp@m.re.co.nosp@m.m

This file is part of the FW Profile.

This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.

For information on alternative licensing, please contact P&P Software GmbH.

Definition in file FwPrSCreate.h.

Macro Definition Documentation

#define FW_PR_INST (   PR_DESC,
  N,
  NDEC,
  NFLOWS,
  NA,
  NG 
)
Value:
static PrANode_t PR_DESC##_aNodes[(N)]; \
static PrDNode_t PR_DESC##_dNodes[(NDEC)]; \
static PrFlow_t PR_DESC##_flows[(NFLOWS)]; \
static FwPrAction_t PR_DESC##_actions[(NA)]; \
static FwPrGuard_t PR_DESC##_guards[(NG) + 1]; \
static PrBaseDesc_t PR_DESC##_base = {(PR_DESC##_aNodes), (PR_DESC##_dNodes), (PR_DESC##_flows), N, NDEC, NFLOWS}; \
static struct FwPrDesc(PR_DESC) = { \
&(PR_DESC##_base), (PR_DESC##_actions), (PR_DESC##_guards), NA, (NG) + 1, 1, 0, prSuccess, 0, 0, NULL};
Structure representing a decision node in a procedure.
Definition: FwPrPrivate.h:121
Structure representing an action node in a procedure.
Definition: FwPrPrivate.h:98
Structure representing the base descriptor of a procedure.
Definition: FwPrPrivate.h:186
void(* FwPrAction_t)(FwPrDesc_t)
Type for a pointer to a procedure action.
Definition: FwPrConstants.h:45
Structure representing a control flow.
Definition: FwPrPrivate.h:152
Return codes of a function which has completed execution without errors.
Definition: FwPrConstants.h:85
FwPrBool_t(* FwPrGuard_t)(FwPrDesc_t)
Type for a pointer to a procedure guard.
Definition: FwPrConstants.h:63

Instantiate a procedure descriptor and its internal data structure.

This macro compiles correctly only if the number of action nodes N, the number of decision NDEC and the number of control flows NFLOWS is positive. If there is a need to define a procedure with zero decision nodes, the FW_PR_INST_NODEC macro should be used.

The macro generates code that does the following:

  • It defines an array of N elements of type PrANode_t to represent the array holding the procedure action nodes.
  • It defines an array of NDEC elements of type PrDNodes_t to represent the array holding the procedure decision nodes.
  • It defines an array of NFLOWS elements of type PrFlow_t to represent the array holding the procedure control flows.
  • It defines an array of NA elements of type PrAction_t to represent the array holding the procedure actions.
  • It defines an array of (NG+1) elements of type PrGuard_t to represent the array holding the procedure guards (the extra guard is the "dummy guard" PrDummyGuard" to be attached to control flows which have no guard).
  • It defines and initializes a variable of type FwPrDescBase_t to represent the base part of the procedure descriptor.
  • It defines and initializes a variable with the name PR_DESC of type struct FwPrDesc to represent the procedure descriptor.

All variables defined by this macro are static.

The procedure descriptor instantiated by the macro is only partially initialized. Full initialization is performed using function FwPrInit.

Since the macro includes the declaration of several variables, it should be located in the section of a c-file where variable declaration is legal.

Parameters
PR_DESCthe variable holding the procedure descriptor
Na positive integer representing the number of action nodes
NDECa positive integer the number of decision nodes
NFLOWSa positive integer representing the number of control flows
NAa positive integer representing the number of actions
NGa non-negative integer representing the number of guards (i.e. the number of transition actions which are defined on the procedure)

Definition at line 102 of file FwPrSCreate.h.

#define FW_PR_INST_DER (   PR_DESC,
  NA,
  NG 
)
Value:
static FwPrAction_t PR_DESC##_actions[(NA)]; \
static FwPrGuard_t PR_DESC##_guards[(NG) + 1]; \
static struct FwPrDesc(PR_DESC) = { \
NULL, (PR_DESC##_actions), (PR_DESC##_guards), NA, (NG) + 1, 1, 0, prSuccess, 0, 0, NULL};
void(* FwPrAction_t)(FwPrDesc_t)
Type for a pointer to a procedure action.
Definition: FwPrConstants.h:45
Return codes of a function which has completed execution without errors.
Definition: FwPrConstants.h:85
FwPrBool_t(* FwPrGuard_t)(FwPrDesc_t)
Type for a pointer to a procedure guard.
Definition: FwPrConstants.h:63

Instantiate a descriptor for a derived procedure.

A derived procedure is a procedure which is created by extending another procedure. The procedure which is thus extended is called base procedure.

A procedure descriptor consists of two parts: the base descriptor and the extension descriptor (see FwPrPrivate.h). A derived procedure and its base procedure share the same base descriptor (which defines the topology of the procedure) but have different extension descriptors. This macro accordingly only instantiates a new extension descriptor. More precisely, this macro generates code that does the following:

  • It defines an array of NA elements of type PrAction_t to represent the array holding the procedure actions.
  • It defines an array of (NG+1) elements of type PrGuard_t to represent the array holding the procedure guards (the extra guard is the "dummy guard" PrDummyGuard" to be attached to control flows which have no guard).
  • It defines and initializes a variable with the name PR_DESC of type struct FwPrDesc to represent the procedure descriptor.

All variables defined by this macro are static.

The procedure descriptor instantiated by the macro is only partially initialized. Full initialization is performed using function FwPrInitDer.

Since the macro includes the declaration of several variables, it should be located in the section of a c-file where variable declaration is legal.

Parameters
PR_DESCthe variable holding the procedure descriptor
NAa non-negative integer representing the number of actions
NGa non-negative integer representing the number of guards

Definition at line 197 of file FwPrSCreate.h.

#define FW_PR_INST_NODEC (   PR_DESC,
  N,
  NFLOWS,
  NA,
  NG 
)
Value:
static PrANode_t PR_DESC##_aNodes[(N)]; \
static PrFlow_t PR_DESC##_flows[(NFLOWS)]; \
static FwPrAction_t PR_DESC##_actions[(NA)]; \
static FwPrGuard_t PR_DESC##_guards[(NG) + 1]; \
static PrBaseDesc_t PR_DESC##_base = {(PR_DESC##_aNodes), NULL, (PR_DESC##_flows), N, 0, NFLOWS}; \
static struct FwPrDesc(PR_DESC) = { \
&(PR_DESC##_base), (PR_DESC##_actions), (PR_DESC##_guards), NA, (NG) + 1, 1, 0, prSuccess, 0, 0, NULL};
Structure representing an action node in a procedure.
Definition: FwPrPrivate.h:98
Structure representing the base descriptor of a procedure.
Definition: FwPrPrivate.h:186
void(* FwPrAction_t)(FwPrDesc_t)
Type for a pointer to a procedure action.
Definition: FwPrConstants.h:45
Structure representing a control flow.
Definition: FwPrPrivate.h:152
Return codes of a function which has completed execution without errors.
Definition: FwPrConstants.h:85
FwPrBool_t(* FwPrGuard_t)(FwPrDesc_t)
Type for a pointer to a procedure guard.
Definition: FwPrConstants.h:63

Instantiate a procedure descriptor and its internal data structure.

This macro compiles correctly only if the number of action nodes N and the number of control flows is positive. This macro instantiates a descriptor for a procedure without decision nodes. If there is a need to define a procedure with one or more decision nodes, the FW_PR_INST macro should be used.

The macro generates code that does the following:

  • It defines an array of N elements of type PrANode_t to represent the array holding the procedure action nodes.
  • It defines an array of NFLOWS elements of type PrFlow_t to represent the array holding the procedure control flows.
  • It defines an array of NA elements of type PrAction_t to represent the array holding the procedure actions.
  • It defines an array of (NG+1) elements of type PrGuard_t to represent the array holding the procedure guards (the extra guard is the "dummy guard" PrDummyGuard" to be attached to control flows which have no guard).
  • It defines and initializes a variable of type FwPrDescBase_t to represent the base part of the procedure descriptor.
  • It defines and initializes a variable with the name PR_DESC of type struct FwPrDesc to represent the procedure descriptor.

All variables defined by this macro are static.

The procedure descriptor instantiated by the macro is only partially initialized. Full initialization is performed using function FwPrInit.

Since the macro includes the declaration of several variables, it should be located in the section of a c-file where variable declaration is legal.

Parameters
PR_DESCthe variable holding the procedure descriptor
Na positive integer representing the number of action nodes
NFLOWSa positive integer representing the number of control flows
NAa positive integer representing the number of actions
NGa non-negative integer representing the number of guards (i.e. the number of transition actions which are defined on the procedure)

Definition at line 153 of file FwPrSCreate.h.

Function Documentation

void FwPrInit ( FwPrDesc_t  prDesc)

Initialize a procedure descriptor to represent an unconfigured procedure with no control flows, no actions, and no guards.

After this function has been executed, the argument procedure descriptor has the same content as a procedure descriptor which has been created by calling FwPrCreate.

This function is primarily intended to be used to initialize a procedure descriptor which has been statically instantiated with macro FW_PR_INST or FW_PR_INST_NODEC.

If the function is called upon a procedure descriptor that had already been initialized, the previous initialization values are lost. In such a case, a memory leak is possible due to the potential loss of the pointers to the arrays where the procedures nodes and control flows are stored.

Parameters
prDescthe procedure descriptor to be initialized.

Definition at line 23 of file FwPrSCreate.c.

void FwPrInitDer ( FwPrDesc_t  prDesc,
FwPrDesc_t  prDescBase 
)

Initialize a procedure descriptor to extend another procedure (the base procedure).

This function checks that the descriptor to be initialized satisfies the following constraints:

  • it has the same number of actions as the base procedure, and
  • it has the same number of guards as the base procedure.

If either constraint is not satisfied, the function reports an error by setting the error code of the descriptor to be initialized and then returns. If the first constraint is not satisfied, the function sets the error code to prWrongNOfActions. If the second constraint is not satisfied, the function sets the error code to prWrongNOfGuards.

If both constraints are satisfied, this function initializes a descriptor as follows:

  • It links it to the descriptor of the base procedure.
  • It initializes its actions to be the same as the actions of the base state machine.
  • It initializes its guards to be the same as the guards of the base state machine.
  • It initializes its error code to be the same as the error code of the base procedure.
  • It initializes its flowCnt field to zero.
  • It sets its state to STOPPED.

Thus, the descriptor initialized by this function represents exactly the same procedure as the descriptor created by calling function FwPrCreateDer.

This function is primarily intended to be used to initialize a procedure descriptor which has been statically instantiated with macro FW_PR_INST_DER. If the function is called upon a procedure descriptor that had already been initialized, the previous initialization values are lost. In such a case, a memory leak is possible due to the potential loss of the pointers to the arrays where the procedures states, choice pseudo-states, transitions and embedded procedures are stored.

Parameters
prDescthe procedure descriptor to be initialized.
prDescBasethe procedure descriptor of the base procedure.

Definition at line 51 of file FwPrSCreate.c.

P&P Software GmbH, Copyright 2011, All Rights Reserved