le_safeRef.h

Go to the documentation of this file.

#ifndef LEGATO_SAFEREF_INCLUDE_GUARD
#define LEGATO_SAFEREF_INCLUDE_GUARD

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#define LIMIT_MAX_SAFE_REF_NAME_LEN     31
#define LIMIT_MAX_SAFE_REF_NAME_BYTES   (LIMIT_MAX_SAFE_REF_NAME_LEN + 1)


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_ref_Map *le_ref_MapRef_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
typedef struct le_ref_Iter *le_ref_IterRef_t;


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
struct le_ref_Block;


// Internal block sizing
#define LE_REF_BLOCK_SIZE(numRefs)  (1 + (numRefs))

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
struct le_ref_Map
{
    le_dls_Link_t        entry;     

#if LE_CONFIG_SAFE_REF_NAMES_ENABLED
    char                 name[LIMIT_MAX_SAFE_REF_NAME_BYTES];   
    le_log_TraceRef_t    traceRef;  
#endif

    size_t               index;     
    bool                 advance;   
    size_t               size;      
    size_t               maxRefs;   
    uint32_t             mapBase;   

    struct le_ref_Block *blocksPtr; 
};

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#define LE_REF_DEFINE_STATIC_MAP(name, maxRefs)                                 \
    static struct le_ref_Map     _ref_##name##Map;                              \
    static void                 *_ref_##name##Data[LE_REF_BLOCK_SIZE(maxRefs)]

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_ref_MapRef_t _le_ref_InitStaticMap
(
#if LE_CONFIG_SAFE_REF_NAMES_ENABLED
    const char      *name,
#endif
    size_t           maxRefs,
    le_ref_MapRef_t  mapPtr,
    void            *data
);

//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
#if LE_CONFIG_SAFE_REF_NAMES_ENABLED
#   define le_ref_InitStaticMap(name, maxRefs) \
        _le_ref_InitStaticMap(#name, (maxRefs), &_ref_##name##Map, _ref_##name##Data)
#else /* if not LE_CONFIG_SAFE_REF_NAMES_ENABLED */
#   define le_ref_InitStaticMap(name, maxRefs) \
    _le_ref_InitStaticMap((maxRefs), &_ref_##name##Map, _ref_##name##Data)
#endif /* end LE_CONFIG_SAFE_REF_NAMES_ENABLED */


#if LE_CONFIG_SAFE_REF_NAMES_ENABLED
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_ref_MapRef_t le_ref_CreateMap
(
    const char *name,
    size_t      maxRefs
);
#else /* if not LE_CONFIG_SAFE_REF_NAMES_ENABLED */
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_ref_MapRef_t _le_ref_CreateMap(size_t maxRefs);
//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
LE_DECLARE_INLINE le_ref_MapRef_t le_ref_CreateMap
(
    const char *name,
    size_t      maxRefs
)
{
    LE_UNUSED(name);
    return _le_ref_CreateMap(maxRefs);
}
#endif /* end LE_CONFIG_SAFE_REF_NAMES_ENABLED */


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void* le_ref_CreateRef
(
    le_ref_MapRef_t mapRef, 
    void*           ptr     
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void* le_ref_Lookup
(
    le_ref_MapRef_t mapRef, 
    void*           safeRef 
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_ref_DeleteRef
(
    le_ref_MapRef_t mapRef, 
    void*           safeRef 
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_ref_IterRef_t le_ref_GetIterator
(
    le_ref_MapRef_t mapRef 
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
le_result_t le_ref_NextNode
(
    le_ref_IterRef_t iteratorRef 
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
const void* le_ref_GetSafeRef
(
    le_ref_IterRef_t iteratorRef 
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void* le_ref_GetValue
(
    le_ref_IterRef_t iteratorRef 
);


//--------------------------------------------------------------------------------------------------
//--------------------------------------------------------------------------------------------------
void le_ref_EnableTrace
(
    le_ref_MapRef_t mapRef 
);

#endif // LEGATO_SAFEREF_INCLUDE_GUARD