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... | |
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.
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.
CrFwInFactoryPoolIndex_t CrFwInFactoryGetMaxNOfInCmd | ( | ) |
Return 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.
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
.
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
.
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.
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.
pckt | the packet holding the InCommand |
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.
pckt | the packet holding 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
.
inCmdInstance | the 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
.
inRepInstance | the InReport to be released |
Definition at line 330 of file CrFwInFactory.c.