FW Profile - C1 Implementation
FwSmDCreate.c File Reference

Implements the dynamical creation functions for the FW State Machine Module. More...

Go to the source code of this file.

Functions

FwSmDesc_t FwSmCreate (FwSmCounterS1_t nOfStates, FwSmCounterS1_t nOfChoicePseudoStates, FwSmCounterS1_t nOfTrans, FwSmCounterS1_t nOfActions, FwSmCounterS1_t nOfGuards)
 Create a new state machine descriptor. More...
 
FwSmDesc_t FwSmCreateDer (FwSmDesc_t smDesc)
 Create the descriptor of a derived state machine. More...
 
void FwSmRelease (FwSmDesc_t smDesc)
 Release the memory which was allocated when the state machine descriptor. More...
 
void FwSmReleaseDer (FwSmDesc_t smDesc)
 Release the memory allocated to a derived state machine descriptor. More...
 
void FwSmReleaseRec (FwSmDesc_t smDesc)
 Recursively release the memory which was allocated when the state machine descriptor was created. More...
 

Detailed Description

Implements the dynamical creation functions for the FW State Machine Module.

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 FwSmDCreate.c.

Function Documentation

FwSmDesc_t FwSmCreate ( FwSmCounterS1_t  nOfStates,
FwSmCounterS1_t  nOfChoicePseudoStates,
FwSmCounterS1_t  nOfTrans,
FwSmCounterS1_t  nOfActions,
FwSmCounterS1_t  nOfGuards 
)

Create a new state machine descriptor.

This function creates the state machine 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 state machine descriptor memory had been allocated before the function was aborted.

It is legal to create a state machine descriptor with no states or with no choice pseudo-states but it is not legal to create a state machine descriptor with no transitions. If the latter is attempted, the function is aborted and returns NULL.

Parameters
nOfStatesthe number of states in the new state machine (a non-negative number).
nOfChoicePseudoStatesthe number of choice pseudo-states in the new state machine (a non-negative integer).
nOfTransthe number of transitions in the new state machine (a positive integer).
nOfActionsthe total number of actions (state actions + transition actions) which the user wishes to define for the state machine. The total number of actions must be a non-negative integer. If the same action appears more than once in a state machine, it is counted only once.
nOfGuardsthe total number of transition guards which the user wishes to define for the state machine. The total number of guards must be a non-negative integer. If the same guard appears more than once in a state machine, it is counted only once.
Returns
the descriptor of the new state machine (or NULL if creation of the data structures to hold the state machine descriptor failed or one of the function parameters had an illegal value).

Definition at line 23 of file FwSmDCreate.c.

FwSmDesc_t FwSmCreateDer ( FwSmDesc_t  smDesc)

Create the descriptor of a derived state machine.

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

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

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

After being created, the derived state machine has the following characteristics:

  • It has the same number of states, choice pseudo-states and transitions as the base state machine.
  • Its states and choice pseudo-states are connected by the same transitions as the base state machine.
  • Its states have the same actions as the homologous states of the base state machine.
  • Its transitions have the same actions and guards and are triggered by the same transition commands as the homologous transitions of the base state machine.
  • States whose homologous states in the base state machine have an embedded state machine also have an embedded state machine: the derivation process is applied recursively to the embedded state machines (i.e. if state S1 in the base state machine has an embedded state machine SM1, then the homologous state in the derived state machine has an embedded state machine which is derived by extending SM1).

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

The attributes of the derived state machine are initialized as follows:

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

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

  • loading its state machine data;
  • overriding some or all of its actions and guards; and
  • embedding state machines in some or all of its states which do not already hold embedded state machines.

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

A state machine descriptor consists of two parts: the base descriptor and the extension descriptor (see FwSmPrivate.h). A derived state machine and its base state machine share the same base descriptor (which defines the topology of the state machine) 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 state machine.

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

Definition at line 137 of file FwSmDCreate.c.

void FwSmRelease ( FwSmDesc_t  smDesc)

Release the memory which was allocated when the state machine descriptor.

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

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

This function only releases the memory of the argument state machine. The memory allocated to embedded state machines is not affected.

Use of this function is subject to the following constraints:

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

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

Parameters
smDescthe descriptor of the state machine.

Definition at line 201 of file FwSmDCreate.c.

void FwSmReleaseDer ( FwSmDesc_t  smDesc)

Release the memory allocated to a derived state machine descriptor.

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

This function only releases the memory of the argument state machine. The memory allocated to embedded state machines is not affected.

Use of this function is subject to the following constraints:

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

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

Parameters
smDescthe descriptor of the state machine.

Definition at line 223 of file FwSmDCreate.c.

void FwSmReleaseRec ( FwSmDesc_t  smDesc)

Recursively release the memory which was allocated when the state machine descriptor was created.

After this operation is called, the state machine descriptor can no longer be used. This operation also (recursively) releases the memory of the state machines embedded in the argument state machine.

The release of the memory for the state machine and its embedded state machines is done by means of function FwSmRelease. The same constraints defined for FwSmRelease therefore also apply to this function.

As in the case of the FwSmRelease, both the the base and the extension parts of the argument state machine descriptor are released. Hence, if the argument state machine or any of its embedded state machines acted as bases for other state machines, the derived state machine descriptors are no longer usable after the function has been called.

Parameters
smDescthe descriptor of the state machine.

Definition at line 239 of file FwSmDCreate.c.

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