State Utilities user

Collaboration diagram for State Utilities user:

Modules
	Macros for the component header
	Macros for the component

---

Detailed Description

macros.

The State Utils macros

Macros are provided to define a component's global state structure, and optionally create a public state structure as part of the global state, for exporting to the component's clients.

Macros are provided to create the component's state structure statically or dynamically (on the heap). Options are provided to specify that the structure is zero-initialisable, or has a constant static initialiser, or is to be initialised and finalised by user-defined functions.

Using the macros:

• In my_component.h:

  • Define the component's public state:

    PUBLIC_STATE_DEF(my_component) { int field1; int field2; ... } PUBLIC_STATE_T(my_component);

    
    

  • Import the component's extern declarations:

    IMPORT(my_component);

  • Or, where the component has no state:

    IMPORT_INITOR(my_component); IMPORT_FINITOR(my_component);

  
  

• In my_component.c:

  • Define the component's gobal state:

    STATE_DEF(my_component) { INCLUDE_PUBLIC(my_component); // Must be first int field3; int field4; ... STATE_T(my_component);

    
    

  • If the component has no public state then the STATE_DEF will instead be:

    STATE_DEF(my_component) { int field1; int field2; ... STATE_T(my_component); NO_PUBLIC_STATE(my_component);

    
    

  • If the component has no private state then instead of the STATE_DEF you need:

    NO_PRIVATE_STATE(my_component);

    
    

  • Define my_component's state as static and zero-initialisable:

    IMPLEMENT_STATIC(my_component,ZERO_INITABLE);

    
    

  • Or static with constant initialiser:

    IMPLEMENT_STATIC(my_component,STATIC_INITABLE); USE_STATIC_INITIALISER(my_component) = { { 1, 2,...}, 3, 4... };

    
    

  • Or static with initialising and finalising functions:

    IMPLEMENT_STATIC(my_component,USER_INITABLE); DEFINE_USER_INIT(my_component)(STATE_T(my_mdoule) * statep) { ... } DEFINE_USER_FINIS(my_component)(STATE_T(my_component) * statep) { ... }

    
    

  • If you implement my_component with the USER_INITABLE option, you must define functions to intialise and finalise the state structure with DEFINE_USER_INIT and DEFINE_USER_FINIS.
    

  • Instead of IMPLEMENT_STATIC you may use IMPLEMENT_DYNAMIC to have the component's state structure allocated on the heap.
    

  • Alternatively you can just use IMPLEMENT. If you define DEFAULT_STATIC_STATE to the compiler, IMPLEMENT is short for IMPLEMENT_STATIC; otherwise it is short for IMPLEMENT_DYNAMIC.

• Initialising and cleaning up component state:

  • Before you can safely access any fields in the component's state structure you must call:

    INITIALISE(my_component);

  • If you every need to dispose of the state structure you must call:

    FINALISE(my_component);

  • You can reinitialise the state structure by calling:

    REINITIALISE(my_component);

  
  

• Accessing component state:

  • Wherever the component's public state is visible, a field can be referenced like this:

    val = GET_PUBLIC(my_component,field);

    
    

    and can be set like this:

    SET_PUBLIC(my_component,field) = val;

    
    

  • Wherever the component's global state is visible, a field can be referenced like this:

    val = GET_STATE(my_component,field);

    
    

    and set like this:

    SET_STATE(my_component,field) = val;

Generated symbols (for debugging):

Symbols that can be generated by the macros for a component my_component are:

• struct my_component_state_s
  • my_component_state
  • The component's global state structure.
  • Note: This symbol will exist if the component is implemented statically.

• typedef struct my_component_state_s
  • my_component_state_t

• struct my_component_public_state_s
  • my_component_public_state
  • The component's public state structure.
  • Note: This symbol will exist if the component is implemented statically.

• typedef struct my_component_public_state_s
  • my_component_public_state_t

• struct my_component_state_s *
  • my_component_h
  • Pointer to the component's global state.
  • Note: This symbol will always address the component's global state, if it has any.

• struct my_component_public_state_s *
  • my_component_public_h
  • Pointer to the component's public state.
  • Note: This symbol will always address the component's public state, if it has any.

• void my_component_init(my_component_state_s *statep)
  • Mandatory name of user-supplied component initialising function, if any. You must define this function if you specify the component with the USER_INITABLE attribute. You can use the macro DEFINE_USER_INIT(my_component) to compose the mandatory signature for this function.

• void my_component_finis(my_component_state_s *statep)
  • Mandatory name of user-supplied component finalising function, if any. You must define this function if you specify the component with the USER_INITABLE attribute. You can use the macro DEFINE_USER_FINIS(my_component) to compose the mandatory signature for this function.
  • Note: my_component_init() and my_component_finis() do not need to control storage for the component's state structure. They can the assume the argument statep addresses that structure and need only initialise and finalise the elements of the structure.

• void (*my_component_init_h)(my_component_state_s *)
  • If you specify the component with the USER_INITABLE attribute, this function pointer will be set to the address of my_component_init() and will otherwise be NULL.

• void (*my_component_finis_h)(my_component_state_s *)
  • If you specify the component with USER_INITABLE, this function pointer will be set to the address of my_component_finis() and will otherwise be NULL.

• const struct my_component_state_s
  • my_component_static_initialiser
  • Mandatory name of the component's constant static initialiser, if any. You can use the macro USE_STATIC_INITIALISER(my_component) to compose the mandatory declaration.

• const struct my_component_state_s *
  • const my_component_static_initialiser_h
  • If you specify the component with HAS_STATIC_INITIALISER, this pointer will be set to the address of my_component_static_initialiser and will otherwise be NULL.