le_cdata.h

    1 /**
    2  * @page c_cdata Component Data API
    3  *
    4  * @subpage le_cdata.h "API Reference" <br>
    5  * <hr>
    6  *
    7  * In some contexts (e.g. on real-time operating systems) a single process may contain multiple
    8  * instances of a component.  Ordinary global or static variables will be shared across all
    9  * instances of the component in the process.  The Legato Component Data API provides a method
   10  * to associate data with a specific component instance.
   11  *
   12  * To create per-component instance data, use the LE_CDATA_DECLARE macro to declare your
   13  * per-instance data at file scope:
   14  *
   15  * @code
   16  * LE_CDATA_DECLARE({
   17  *     int numFoo;
   18  *     char* fooStr;
   19  * });
   20  * @endcode
   21  *
   22  * Only one component instance data can be declared per-file, and this data is only available
   23  * within the file where it's declared.
   24  *
   25  * Then use @c LE_CDATA_THIS to access the current component instance's data.  For example:
   26  * @code
   27  * LE_CDATA_THIS->numFoo = 5;
   28  * @endcode
   29  *
   30  * <hr>
   31  *
   32  * Copyright (C) Sierra Wireless Inc.
   33  */
   34 
   35 /**
   36  * @file le_cdata.h
   37  *
   38  * Legato @ref c_cdata include file.
   39  *
   40  * Copyright (C) Sierra Wireless Inc.
   41  */
   42 
   43 #ifndef LEGATO_CDATA_INCLUDE_GUARD
   44 #define LEGATO_CDATA_INCLUDE_GUARD
   45 
   46 #ifndef LE_CDATA_COMPONENT_COUNT
   47     // If legato.h is used in a program built outside of the mktools framework there's only one
   48     // instance of each component.
   49 #   define LE_CDATA_COMPONENT_COUNT 1
   50 #endif
   51 
   52 //--------------------------------------------------------------------------------------------------
   53 /**
   54  * Map component key to a component instance number.
   55  */
   56 //--------------------------------------------------------------------------------------------------
   57 typedef struct
   58 {
   59     short key;
   60     short instance;
   61 } _le_cdata_MapEntry_t;
   62 typedef const _le_cdata_MapEntry_t _le_cdata_ThreadRec_t;
   63 
   64 /**
   65  * Define per-component instance data.
   66  */
   67 #define LE_CDATA_DECLARE(x) static struct x _le_cdata_Instance[LE_CDATA_COMPONENT_COUNT]
   68 
   69 #if LE_CDATA_COMPONENT_COUNT == 1
   70 /* Only one instance of this component; macros refer to a simple structure.
   71  * This is optimized to avoid TLS lookup if there's only one instance of the component,
   72  * which is the most common case. */
   73 /**
   74  * Fetch per-instance data for the current instance.
   75  */
   76 #   define LE_CDATA_THIS    (&_le_cdata_Instance[0])
   77 #else
   78 /**
   79  * Fetch per-instance data for the current instance.
   80  */
   81 #   define LE_CDATA_THIS    (&_le_cdata_Instance[le_cdata_GetInstance(LE_CDATA_KEY)])
   82 #endif
   83 
   84 /**
   85  * Get this component instance.
   86  *
   87  * @note This should typically not be used by a user application; use LE_CDATA_THIS instead.
   88  */
   89 unsigned int le_cdata_GetInstance(unsigned int componentKey);
   90 
   91 #endif /* LEGATO_CDATA_INCLUDE_GUARD */
_le_cdata_MapEntry_t
Definition: le_cdata.h:57
le_cdata_GetInstance
unsigned int le_cdata_GetInstance(unsigned int componentKey)