CORDET Framework - C2 Implementation

Definition of the InFactory component. More...

Go to the source code of this file.

Functions

FwSmDesc_t CrFwInFactoryMake ()
 Factory function for the singleton instance of the InFactory. More...
 
FwSmDesc_t CrFwInFactoryMakeInRep (CrFwPckt_t pckt)
 Make function for a component encapsulating an incoming report (InReport). More...
 
FwSmDesc_t CrFwInFactoryMakeInCmd (CrFwPckt_t pckt)
 Make function for a component encapsulating an incoming command (InCommand). More...
 
void CrFwInFactoryReleaseInRep (FwSmDesc_t inRepInstance)
 Release function for an InReport. More...
 
void CrFwInFactoryReleaseInCmd (FwSmDesc_t inCmdInstance)
 Release function for an InCommand. More...
 
CrFwInFactoryPoolIndex_t CrFwInFactoryGetNOfAllocatedInRep ()
 Return the number of InReports which are currently allocated. More...
 
CrFwInFactoryPoolIndex_t CrFwInFactoryGetMaxNOfInRep ()
 Return the maximum number of InReports which may be allocated at any one time. More...
 
CrFwInFactoryPoolIndex_t CrFwInFactoryGetNOfAllocatedInCmd ()
 Return the number of InCommands which are currently allocated. More...
 
CrFwInFactoryPoolIndex_t CrFwInFactoryGetMaxNOfInCmd ()
 Return the maximum number of InCommands which may be allocated at any one time. More...
 

Detailed Description

Definition of the InFactory component.

The InFactory component offers an interface through which incoming report components (InReports, see CrFwInRep.h) or incoming command components (InCommands, see CrFwInCmd.h be allocated and released.

The InFactory is implemented as an extension of the Base Component of CrFwBaseCmp.h. The InFactory is a singleton component.

This interface provides a function to create the InFactory, it provides functions to create an InReport or an InCommand of a specified kind, and it provides functions to release previously allocated InReports or InCommands.

The InFactory maintains a pool of pre-allocated InReports and a pool of pre-allocated InCommands (the sizes of the pools are defined in CrFwInFactoryUserPar.h). Memory for the pools is allocated when the InFactory is initialized and is only released if the InFactory is shutdown. Items in the pool are marked as "in use" when they are allocated to an application and are marked as "not in use" when they are released. No memory allocation operations (malloc/free) are therefore performed when InReports or InCommands are allocated or released. When the InFactory is reset, all the items in the pool are marked as "not in use".

Mode of Use of an InFactory Component

The configuration of the InFactory component is defined statically in CrFwInFactoryUserPar.h.

The InFactory is created with function CrFwInFactoryMake. After being created, the InFactory must be initialized and reset. This is done with functions CrFwCmpInit and CrFwCmpReset. Nominally, after being initialized and reset the InFactory State Machine should be in state CONFIGURED (this can be checked by verifying that function FwSmGetCurState returns CR_FW_BASE_STATE_CONFIGURED).

After being configured, the InFactory is ready to manage the creation and release process for InReports and InCommands. An InReport is created with function CrFwInFactoryMakeInRep and it is released with function CrFwInFactoryReleaseInRep. Similarly, an InCommand is created with function CrFwInFactoryMakeInCmd and it is released with function CrFwInFactoryReleaseInCmd.

An InReport wraps a packet holding an incoming report and an InCommand wraps a packet holding an incoming command. The packet holding the report or command is passed as an argument to the make function which creates the InReport or InCommand component.

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 CORDET Framework.

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

Function Documentation

CrFwInFactoryPoolIndex_t CrFwInFactoryGetMaxNOfInCmd ( )

Return the maximum number of InCommands which may be allocated at any one time.

Returns
the maximum number of InCommands which may be allocated at any one time

Definition at line 356 of file CrFwInFactory.c.

CrFwInFactoryPoolIndex_t CrFwInFactoryGetMaxNOfInRep ( )

Return the maximum number of InReports which may be allocated at any one time.

Returns
the maximum number of InReports which may be allocated at any one time

Definition at line 366 of file CrFwInFactory.c.

CrFwInFactoryPoolIndex_t CrFwInFactoryGetNOfAllocatedInCmd ( )

Return the number of InCommands which are currently allocated.

This function returns the number of InCommands which have been successfully allocated through calls to CrFwInFactoryMakeInCmd and have not yet been released through calls to CrFwInFactoryReleaseInCmd.

Returns
the number of InCommands which are currently allocated.

Definition at line 351 of file CrFwInFactory.c.

CrFwInFactoryPoolIndex_t CrFwInFactoryGetNOfAllocatedInRep ( )

Return the number of InReports which are currently allocated.

This function returns the number of InReports which have been successfully allocated through calls to CrFwInFactoryMakeInRep and have not yet been released through calls to CrFwInFactoryReleaseInRep.

Returns
the number of InReports which are currently allocated.

Definition at line 361 of file CrFwInFactory.c.

FwSmDesc_t CrFwInFactoryMake ( )

Factory function for the singleton instance of the InFactory.

The first time it is called, this function creates the InFactory singleton instance. Subsequent calls return the same instance. The first time this function is called, it returns the InFactory in state CREATED.

Returns
the OutFactory singleton instance.

Definition at line 151 of file CrFwInFactory.c.

FwSmDesc_t CrFwInFactoryMakeInCmd ( CrFwPckt_t  pckt)

Make function for a component encapsulating an incoming command (InCommand).

This function initializes and resets a component before returning it. Under nominal conditions, the component returned by this function is therefore in state CONFIGURED (but it could be in state INITIALIZED if the InCommand's configuration check fails).

An InCommand encapsulates an incoming packet holding a command. The packet is passed as an argument to this function. The packet holds all the information about the incoming command. In particular, it holds the information about the command kind (as determined by the triplet: [service type, service sub-type, discriminant]). This function checks the command kind and, if it finds that it is illegal, it returns NULL and sets the application error code to: crIllInCmdKind). If instead the command is legal, this function uses it to configure the InCommand. The configuration information is retrieved from CrFwInFactoryUserPar.

The Progress Step of the InCommands returned by this function is initialized to 0. Likewise, the completion status of the progress action of the InCommand is initialized to 1 indicating "completed" (this results in an InCommand whose progress action is only executed once). The counter of failed progress steps is initialized to zero.

If the allocation of the memory for the new InCommand fails, the function returns NULL. Allocation memory failure results in the application error code being set to crInCmdAllocationFail.

When an InCommand created by this function is no longer needed, it should be returned to the factory by calling CrFwInFactoryReleaseInCmd.

If the InFactory is reset, then all the InCommands which had been created by the factory are released.

Parameters
pcktthe packet holding the InCommand
Returns
a new InCommand or NULL if it was not possible to allocate the memory for the InCommand or if the packet type is not recognized.

Definition at line 195 of file CrFwInFactory.c.

FwSmDesc_t CrFwInFactoryMakeInRep ( CrFwPckt_t  pckt)

Make function for a component encapsulating an incoming report (InReport).

This function initializes and resets a component before returning it. Under nominal conditions, the component returned by this function is therefore in state CONFIGURED (but it could be in state INITIALIZED if the InReport's configuration check fails).

An InReport encapsulates an incoming packet holding a report. The packet is passed as an argument to this function. The packet holds all the information about the incoming report. In particular, it holds the information about the report kind (as determined by the triplet: [service type, service sub-type, discriminant]). This function checks the report kind and, if it finds that it is illegal, it returns NULL and sets the application error code to: crIllInRepKind). If instead the command is legal, this function uses it to configure the InReport. The configuration information is retrieved from CrFwInFactoryUserPar.

If the allocation of the memory for the new InReport fails, the function returns NULL. Allocation memory failure results in the application error code being set to crInRepAllocationFail.

When an InReport created by this function is no longer needed, it should be returned to the factory by calling CrFwInRepReleaseInRep.

The instance identifier of the InReport created by this function is equal to the number of InReports created by the factory since it was last reset.

If the InFactory is reset, then all the InReports which had been created by the factory are released.

Parameters
pcktthe packet holding the InReport
Returns
a new InReport or NULL if it was not possible to allocate the memory for the InReport.

Definition at line 256 of file CrFwInFactory.c.

void CrFwInFactoryReleaseInCmd ( FwSmDesc_t  inCmdInstance)

Release function for an InCommand.

The argument of this function must be an InCommand which was created using function CrFwInFactoryMakeInCmd. This function releases the memory which was allocated to the InCommand. After this function is called, the InCommand cannot be used. The function does not perform any checks on the existence or status of the InCommand. An attempt to use an InCommand which has been released will result in undefined behaviour.

An attempt to release an InCommand which had already been released, or to release a non-existent InCommand will result in undefined behaviour and in the application error code being set to: crInCmdRelErr.

Parameters
inCmdInstancethe InCommand to be released

Definition at line 309 of file CrFwInFactory.c.

void CrFwInFactoryReleaseInRep ( FwSmDesc_t  inRepInstance)

Release function for an InReport.

The argument of this function must be an InReport which was created using function CrFwInFactoryMakeInRep. This function releases the memory which was allocated to the InReport. After this function is called, the InReport cannot be used. The function does not perform any checks on the existence or status of the InReport. An attempt to use an InReport which has been released will result in undefined behaviour.

An attempt to release an InReport which had already been released, or to release a non-existent InReport will result in undefined behaviour and in the application error code being set to: crInRepRelErr.

Parameters
inRepInstancethe InReport to be released

Definition at line 330 of file CrFwInFactory.c.

P&P Software GmbH, Copyright 2012-2013, All Rights Reserved