FW Profile - C1 Implementation
FwPrDCreate.h File Reference

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

Go to the source code of this file.

Functions

FwPrDesc_t FwPrCreate (FwPrCounterS1_t nOfANodes, FwPrCounterS1_t nOfDNodes, FwPrCounterS1_t nOfFlows, FwPrCounterS1_t nOfActions, FwPrCounterS1_t nOfGuards)
 Create a new procedure descriptor. More...
 
FwPrDesc_t FwPrCreateDer (FwPrDesc_t prDesc)
 Create the descriptor of a derived procedure. More...
 
void FwPrRelease (FwPrDesc_t prDesc)
 Release the memory which was allocated when the procedure descriptor was created. More...
 
void FwPrReleaseDer (FwPrDesc_t prDesc)
 Release the memory allocated to a derived procedure descriptor. More...
 

Detailed Description

Declaration of the dynamical creation interface for a FW Procedure.

A FW Procedure is described by a procedure descriptor. This interface declares the functions required to create and release a procedure descriptor dynamically. Dynamic creation and release of memory is done through calls to malloc and free.

A procedure can be created in two ways:

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

The functions offered by this interface cover both creation of a new procedure descriptor from scratch (FwPrCreate) and the extension of an existing procedure descriptor to create the descriptor for a derived procedure (FwPrCreateDer).

Both the creation and the extension functions create a new procedure descriptor and return a pointer to the newly created descriptor instance. The procedure descriptor returned by these functions is initialized (i.e. all its attributes have a well-defined value) but will normally need to be configured. Configuration can be done using the functions offered by FwPrConfig.h.

The creation and the extension functions in this header file always check the success of calls to malloc. In case of failure, the function aborts and returns a NULL pointer. Memory which had already been allocated at the time the function aborts, is not released.

Applications which do not wish to use dynamic memory allocation can create a procedure descriptor statically using the services offered by FwPrSCreate.h.

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 FwPrDCreate.h.

Function Documentation

FwPrDesc_t FwPrCreate ( FwPrCounterS1_t  nOfANodes,
FwPrCounterS1_t  nOfDNodes,
FwPrCounterS1_t  nOfFlows,
FwPrCounterS1_t  nOfActions,
FwPrCounterS1_t  nOfGuards 
)

Create a new procedure descriptor.

This function creates the procedure descriptor and its internal data structures dynamically through calls to malloc. If any of these calls fails, the function aborts and returns NULL. In this case, there may be a memory leak if part of the procedure descriptor memory had been allocated before the function was aborted.

It is legal to create a procedure descriptor with no decision nodes but it is not legal to create a procedure descriptor with no control flows or with no action nodes.

Parameters
nOfANodesthe number of action nodes in the new procedure (a positive integer).
nOfDNodesthe number of decision nodes in the new procedure (a non-negative integer).
nOfFlowsthe number of control flows in the new procedure (an integer greater than 1).
nOfActionsthe total number of actions which the user wishes to define for the procedure. The total number of actions must be a positive integer not greater than the number of action nodes. If the same action appears more than once in a procedure, it is counted only once.
nOfGuardsthe total number of control flow guards which the user wishes to define for the procedure. The total number of guards must be a non-negative integer not greater than the number control flows. If the same guard appears more than once in a procedure, it is counted only once.
Returns
the descriptor of the new procedure (or NULL if creation of the data structures to hold the procedure descriptor failed or one of the function parameters had an illegal value).

Definition at line 23 of file FwPrDCreate.c.

FwPrDesc_t FwPrCreateDer ( FwPrDesc_t  prDesc)

Create the descriptor of 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.

This function takes a procedure as an argument and creates a derived procedure from it. The function returns the descriptor of the newly created derived procedure.

The base procedure should be fully and correctly configured (i.e. it should pass the configuration check implemented by FwPrCheck). Compliance with this constraint is not checked by this function. If the constraint is not satisfied, the behaviour of the derived procedure is undefined.

After being created, the derived procedure has the following characteristics:

  • It has the same number of action and decision nodes as the base procedure.
  • Its action and decision nodes are connected by the same control flows as the base procedure.
  • Its action nodes have the same actions as the homologous nodes of the base node machine.
  • Its control flows have the same guards as the homologous control flows of the base procedure.

Thus, the derived procedure is a structural clone of its base procedure.

The attributes of the derived procedure are initialized as follows:

  • The error code is the same as the error code of the base procedure.
  • No procedure data are associated to the derived procedure.
  • The execution counters are equal to zero
  • The procedure state is STOPPED.
  • The flowCnt field in the procedure descriptor is initialized to zero.

After being created, the derived procedure is fully configured because it inherits the configuration of its base procedure. The configuration of a derived procedure can be modified by:

  • loading its procedure data, and
  • overriding some or all of its actions and guards.

The functions to perform these reconfiguration operations are defined in FwPrConfig.h.

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. The extension descriptor is linked to the base descriptor through a pointer. This function accordingly creates a new extension descriptor and links it to the base descriptor of the base procedure.

Parameters
prDescthe descriptor of the base procedure. The base procedure should be a fully and correctly configured procedure (i.e. it should pass the FwPrCheck configuration check).
Returns
the descriptor of the derived procedure (or NULL if creation of the data structures to hold the extended procedure descriptor failed).

Definition at line 132 of file FwPrDCreate.c.

void FwPrRelease ( FwPrDesc_t  prDesc)

Release the memory which was allocated when the procedure descriptor was created.

After this operation is called, the procedure descriptor can no longer be used.

This function releases the memory of both the base and the extension parts of the procedure descriptor. Hence, if the argument procedure descriptor acted as base for other procedure descriptors, the derived procedure descriptors are no longer usable after the function has been called.

Use of this function is subject to the following constraints:

  • It should only be called on a procedure descriptor which was created using function FwPrCreate.
  • It should only be called once on the same procedure descriptor.
  • It should only be called on a procedure descriptor which is correctly configured.

Violation of any of the above constraints may result in memory corruption.

Parameters
prDescthe descriptor of the procedure.

Definition at line 175 of file FwPrDCreate.c.

void FwPrReleaseDer ( FwPrDesc_t  prDesc)

Release the memory allocated to a derived procedure descriptor.

After this operation is called, the argument procedure descriptor can no longer be used. The procedure descriptor of the base procedure is unaffected by this function.

Use of this function is subject to the following constraints:

  • It should only be called on a procedure descriptor which was created using function FwPrCreateDer.
  • It should only be called once on the same procedure descriptor.
  • It should only be called on a procedure descriptor which is correctly configured.

Violation of any of the above constraints may result in memory corruption.

Parameters
prDescthe descriptor of the procedure.

Definition at line 205 of file FwPrDCreate.c.

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