Detailed Description

Collaboration diagram for Objects Caches:

Cached objects flags
#define	OC_FLAG_INLRU 0x00000001U
#define	OC_FLAG_INHASH 0x00000002U
#define	OC_FLAG_SHARED 0x00000004U
#define	OC_FLAG_NOTSYNC 0x00000008U
#define	OC_FLAG_LAZYWRITE 0x00000010U
#define	OC_FLAG_FORGET 0x00000020U

Data Structures
struct	ch_oc_hash_header
	Structure representing an hash table element. More...
struct	ch_oc_lru_header
	Structure representing an hash table element. More...
struct	ch_oc_object
	Structure representing a cached object. More...
struct	ch_objects_cache
	Structure representing a cache object. More...

Macros
#define	OC_HASH_FUNCTION(ocp, group, key)
#define	HASH_INSERT(ocp, objp, group, key)
#define	HASH_REMOVE(objp)
#define	LRU_INSERT_HEAD(ocp, objp)
#define	LRU_INSERT_TAIL(ocp, objp)
#define	LRU_REMOVE(objp)

Typedefs
typedef uint32_t	oc_flags_t
	Flags of cached objects.
typedef struct ch_oc_hash_header	oc_hash_header_t
	Type of an hash element header.
typedef struct ch_oc_lru_header	oc_lru_header_t
	Type of an LRU element header.
typedef struct ch_oc_object	oc_object_t
	Type of a cached object.
typedef struct ch_objects_cache	objects_cache_t
	Type of a cache object.
typedef bool(*	oc_readf_t) (objects_cache_t ocp, oc_object_t objp, bool async)
	Object read function.
typedef bool(*	oc_writef_t) (objects_cache_t ocp, oc_object_t objp, bool async)
	Object write function.

Functions
static oc_object_t *	hash_get_s (objects_cache_t *ocp, uint32_t group, uint32_t key)
	Returns an object pointer from the cache, if present.
static oc_object_t *	lru_get_last_s (objects_cache_t *ocp)
	Gets the least recently used object buffer from the LRU list.
void	chCacheObjectInit (objects_cache_t ocp, ucnt_t hashn, oc_hash_header_t hashp, ucnt_t objn, size_t objsz, void *objvp, oc_readf_t readf, oc_writef_t writef)
	Initializes a `objects_cache_t` object.
oc_object_t *	chCacheGetObject (objects_cache_t *ocp, uint32_t group, uint32_t key)
	Retrieves an object from the cache.
void	chCacheReleaseObjectI (objects_cache_t ocp, oc_object_t objp)
	Releases an object into the cache.
bool	chCacheReadObject (objects_cache_t ocp, oc_object_t objp, bool async)
	Reads object data from the storage.
bool	chCacheWriteObject (objects_cache_t ocp, oc_object_t objp, bool async)
	Writes the object data back to storage.
static void	chCacheReleaseObject (objects_cache_t ocp, oc_object_t objp)
	Releases an object into the cache.

Macro Definition Documentation

◆ OC_HASH_FUNCTION

#define OC_HASH_FUNCTION	(	ocp,
		group,
		key )

Value:

(((unsigned)(group) + (unsigned)(key)) & ((unsigned)(ocp)->hashn - 1U))

Definition at line 64 of file chobjcaches.c.

Referenced by hash_get_s().

◆ HASH_INSERT

#define HASH_INSERT	(	ocp,
		objp,
		group,
		key )

Value:

  {                                \
  oc_hash_header_t *hhp;                                                    \
  (hhp) = &(ocp)->hashp[OC_HASH_FUNCTION(ocp, group, key)];                 \
  (objp)->hash_next = (hhp)->hash_next;                                     \
  (objp)->hash_prev = (oc_object_t *)(hhp);                                 \
  (hhp)->hash_next->hash_prev = (objp);                                     \
  (hhp)->hash_next = (objp);                                                \
}

Definition at line 69 of file chobjcaches.c.

Referenced by chCacheGetObject().

◆ HASH_REMOVE

#define HASH_REMOVE ( objp )

Value:

  {                                                 \
  (objp)->hash_prev->hash_next = (objp)->hash_next;                         \
  (objp)->hash_next->hash_prev = (objp)->hash_prev;                         \
}

Definition at line 79 of file chobjcaches.c.

Referenced by chCacheReleaseObjectI(), and lru_get_last_s().

◆ LRU_INSERT_HEAD

#define LRU_INSERT_HEAD	(		ocp,
			objp )

Value:

  {                                        \
  (objp)->lru_next = (ocp)->lru.lru_next;                                   \
  (objp)->lru_prev = (oc_object_t *)&(ocp)->lru;                            \
  (ocp)->lru.lru_next->lru_prev = (objp);                                   \
  (ocp)->lru.lru_next = (objp);                                             \
}

Definition at line 85 of file chobjcaches.c.

Referenced by chCacheObjectInit(), and chCacheReleaseObjectI().

◆ LRU_INSERT_TAIL

#define LRU_INSERT_TAIL	(		ocp,
			objp )

Value:

  {                                        \
  (objp)->lru_prev = (ocp)->lru.lru_prev;                                   \
  (objp)->lru_next = (oc_object_t *)&(ocp)->lru;                            \
  (ocp)->lru.lru_prev->lru_next = (objp);                                   \
  (ocp)->lru.lru_prev = (objp);                                             \
}

Definition at line 93 of file chobjcaches.c.

Referenced by chCacheReleaseObjectI().

◆ LRU_REMOVE

#define LRU_REMOVE ( objp )

Value:

  {                                                  \
  (objp)->lru_prev->lru_next = (objp)->lru_next;                            \
  (objp)->lru_next->lru_prev = (objp)->lru_prev;                            \
}

Definition at line 101 of file chobjcaches.c.

Referenced by chCacheGetObject(), and lru_get_last_s().

◆ OC_FLAG_INLRU

#define OC_FLAG_INLRU 0x00000001U

Definition at line 41 of file chobjcaches.h.

Referenced by chCacheGetObject(), chCacheObjectInit(), chCacheReleaseObjectI(), and lru_get_last_s().

◆ OC_FLAG_INHASH

#define OC_FLAG_INHASH 0x00000002U

Definition at line 42 of file chobjcaches.h.

Referenced by chCacheGetObject(), chCacheReleaseObjectI(), and lru_get_last_s().

◆ OC_FLAG_SHARED

#define OC_FLAG_SHARED 0x00000004U

Definition at line 43 of file chobjcaches.h.

Referenced by chCacheReleaseObjectI().

◆ OC_FLAG_NOTSYNC

#define OC_FLAG_NOTSYNC 0x00000008U

Definition at line 44 of file chobjcaches.h.

Referenced by chCacheGetObject(), chCacheReadObject(), and chCacheReleaseObjectI().

◆ OC_FLAG_LAZYWRITE

#define OC_FLAG_LAZYWRITE 0x00000010U

Definition at line 45 of file chobjcaches.h.

Referenced by chCacheReleaseObjectI(), chCacheWriteObject(), and lru_get_last_s().

◆ OC_FLAG_FORGET

#define OC_FLAG_FORGET 0x00000020U

Definition at line 46 of file chobjcaches.h.

Referenced by chCacheReleaseObjectI(), and lru_get_last_s().

Typedef Documentation

◆ oc_flags_t

typedef uint32_t oc_flags_t

Flags of cached objects.

Definition at line 68 of file chobjcaches.h.

◆ oc_hash_header_t

typedef struct ch_oc_hash_header oc_hash_header_t

Type of an hash element header.

Definition at line 73 of file chobjcaches.h.

◆ oc_lru_header_t

typedef struct ch_oc_lru_header oc_lru_header_t

Type of an LRU element header.

Definition at line 78 of file chobjcaches.h.

◆ oc_object_t

typedef struct ch_oc_object oc_object_t

Type of a cached object.

Definition at line 83 of file chobjcaches.h.

◆ objects_cache_t

typedef struct ch_objects_cache objects_cache_t

Type of a cache object.

Definition at line 88 of file chobjcaches.h.

◆ oc_readf_t

typedef bool(* oc_readf_t) (objects_cache_t *ocp, oc_object_t *objp, bool async)

Object read function.

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	async	requests an asynchronous operation if supported, the function is then responsible for releasing the object

Definition at line 98 of file chobjcaches.h.

◆ oc_writef_t

typedef bool(* oc_writef_t) (objects_cache_t *ocp, oc_object_t *objp, bool async)

Object write function.

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	async	requests an asynchronous operation if supported, the function is then responsible for releasing the object

Definition at line 110 of file chobjcaches.h.

Function Documentation

◆ hash_get_s()

oc_object_t * hash_get_s	(	objects_cache_t *	ocp,
		uint32_t	group,
		uint32_t	key )

static

Returns an object pointer from the cache, if present.

Parameters

[out]	ocp	pointer to the `objects_cache_t` structure to be
[in]	group	object group identifier
[in]	key	object identifier within the group initialized

Returns: The pointer to the retrieved object.

Return values

NULL	if the object is not in cache.

Function Class:: Not an API, this function is for internal use only.

Definition at line 134 of file chobjcaches.c.

References ch_oc_hash_header::hash_next, ch_oc_object::hash_next, ch_objects_cache::hashp, ch_oc_object::obj_group, ch_oc_object::obj_key, and OC_HASH_FUNCTION.

Referenced by chCacheGetObject().

◆ lru_get_last_s()

oc_object_t * lru_get_last_s ( objects_cache_t * ocp )

static

Gets the least recently used object buffer from the LRU list.

Parameters

[out] ocp pointer to the objects_cache_t structure to be

Returns: The pointer to the retrieved object.

Function Class:: Not an API, this function is for internal use only.

Definition at line 165 of file chobjcaches.c.

References chDbgAssert, chSemFastWaitI, chSemGetCounterI, chSemWaitS, chSysLock, chSysUnlock, HASH_REMOVE, ch_objects_cache::lru, ch_oc_lru_header::lru_prev, LRU_REMOVE, ch_objects_cache::lru_sem, ch_oc_object::obj_flags, ch_oc_object::obj_sem, OC_FLAG_FORGET, OC_FLAG_INHASH, OC_FLAG_INLRU, OC_FLAG_LAZYWRITE, and ch_objects_cache::writef.

Referenced by chCacheGetObject().

◆ chCacheObjectInit()

void chCacheObjectInit	(	objects_cache_t *	ocp,
		ucnt_t	hashn,
		oc_hash_header_t *	hashp,
		ucnt_t	objn,
		size_t	objsz,
		void *	objvp,
		oc_readf_t	readf,
		oc_writef_t	writef )

Initializes a objects_cache_t object.

Parameters

[out]	ocp	pointer to the `objects_cache_t` structure to be initialized
[in]	hashn	number of elements in the hash table array, must be a power of two and not lower than `objn`
[in]	hashp	pointer to the hash table as an array of `oc_hash_header_t`
[in]	objn	number of elements in the objects table array
[in]	objsz	size of elements in the objects table array, the minimum value is sizeof (oc_object_t).
[in]	objvp	pointer to the hash objects as an array of structures starting with an `oc_object_t`
[in]	readf	pointer to an object reader function
[in]	writef	pointer to an object writer function

Function Class:: Object or module nitializer function.

Definition at line 240 of file chobjcaches.c.

References ch_objects_cache::cache_sem, chDbgCheck, chSemObjectInit, ch_oc_object::dptr, ch_oc_hash_header::hash_next, ch_oc_lru_header::hash_next, ch_oc_hash_header::hash_prev, ch_oc_lru_header::hash_prev, ch_objects_cache::hashn, ch_objects_cache::hashp, ch_objects_cache::lru, LRU_INSERT_HEAD, ch_oc_lru_header::lru_next, ch_oc_lru_header::lru_prev, ch_objects_cache::lru_sem, ch_oc_object::obj_flags, ch_oc_object::obj_group, ch_oc_object::obj_key, ch_oc_object::obj_sem, ch_objects_cache::objn, ch_objects_cache::objvp, OC_FLAG_INLRU, PORT_NATURAL_ALIGN, ch_objects_cache::readf, and ch_objects_cache::writef.

◆ chCacheGetObject()

oc_object_t * chCacheGetObject	(	objects_cache_t *	ocp,
		uint32_t	group,
		uint32_t	key )

Retrieves an object from the cache.

Note: If the object is not in cache then the returned object is marked as OC_FLAG_NOTSYNC meaning that its data contains garbage and must be initialized.

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	group	object group identifier
[in]	key	object identifier within the group

Returns: The pointer to the retrieved object.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 303 of file chobjcaches.c.

References chDbgAssert, chSemFastWaitI, chSemGetCounterI, chSemWaitS, chSysLock, chSysUnlock, hash_get_s(), HASH_INSERT, lru_get_last_s(), LRU_REMOVE, ch_oc_object::obj_flags, ch_oc_object::obj_group, ch_oc_object::obj_key, ch_oc_object::obj_sem, OC_FLAG_INHASH, OC_FLAG_INLRU, and OC_FLAG_NOTSYNC.

Here is the call graph for this function:

◆ chCacheReleaseObjectI()

void chCacheReleaseObjectI	(	objects_cache_t *	ocp,
		oc_object_t *	objp )

Releases an object into the cache.

Note

This function gives a meaning to the following flags:

OC_FLAG_INLRU must be cleared.
OC_FLAG_INHASH must be set.
OC_FLAG_SHARED must be cleared.
OC_FLAG_NOTSYNC invalidates the object and queues it on the LRU tail.
OC_FLAG_LAZYWRITE is ignored and kept, a write will occur when the object is removed from the LRU list (lazy write).

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	objp	pointer to the `oc_object_t` structure

Function Class:: This is an I-Class API, this function can be invoked from within a system lock zone by both threads and interrupt handlers.

Definition at line 378 of file chobjcaches.c.

References chDbgAssert, chSemFastSignalI, chSemGetCounterI, chSemSignalI(), HASH_REMOVE, LRU_INSERT_HEAD, LRU_INSERT_TAIL, ch_objects_cache::lru_sem, ch_oc_object::obj_flags, ch_oc_object::obj_group, ch_oc_object::obj_key, ch_oc_object::obj_sem, OC_FLAG_FORGET, OC_FLAG_INHASH, OC_FLAG_INLRU, OC_FLAG_LAZYWRITE, OC_FLAG_NOTSYNC, and OC_FLAG_SHARED.

Referenced by chCacheReleaseObject().

Here is the call graph for this function:

◆ chCacheReadObject()

bool chCacheReadObject	(	objects_cache_t *	ocp,
		oc_object_t *	objp,
		bool	async )

Reads object data from the storage.

Note: In case of asynchronous operation an error condition is not reported by this function.

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	objp	pointer to the `oc_object_t` structure
[in]	async	requests an asynchronous operation if supported, the function is then responsible for releasing the object

Returns: The operation status. In case of asynchronous operation false is always returned.

Return values

false	if the operation succeeded.
true	if the synchronous read operation failed.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 448 of file chobjcaches.c.

References ch_oc_object::obj_flags, OC_FLAG_NOTSYNC, and ch_objects_cache::readf.

◆ chCacheWriteObject()

bool chCacheWriteObject	(	objects_cache_t *	ocp,
		oc_object_t *	objp,
		bool	async )

Writes the object data back to storage.

Note: In case of asynchronous operation an error condition is not reported by this function.

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	objp	pointer to the `oc_object_t` structure
[in]	async	requests an asynchronous operation if supported, the function is then responsible for releasing the object

Returns: The operation status. In case of asynchronous operation false is always returned.

Return values

false	if the operation succeeded.
true	if the synchronous write operation failed.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 477 of file chobjcaches.c.

References ch_oc_object::obj_flags, OC_FLAG_LAZYWRITE, and ch_objects_cache::writef.

◆ chCacheReleaseObject()

void chCacheReleaseObject	(	objects_cache_t *	ocp,
		oc_object_t *	objp )

inlinestatic

Releases an object into the cache.

Note

This function gives a meaning to the following flags:

OC_FLAG_INLRU must be cleared.
OC_FLAG_INHASH must be set.
OC_FLAG_SHARED must be cleared.
OC_FLAG_NOTSYNC invalidates the object and queues it on the LRU tail.
OC_FLAG_LAZYWRITE is ignored and kept, a write will occur when the object is removed from the LRU list (lazy write).

Parameters

[in]	ocp	pointer to the `objects_cache_t` structure
[in]	objp	pointer to the `oc_object_t` structure

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 295 of file chobjcaches.h.

References chCacheReleaseObjectI(), chSchRescheduleS(), chSysLock, and chSysUnlock.

Here is the call graph for this function:

Detailed Description

Cached objects flags

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ OC_HASH_FUNCTION

◆ HASH_INSERT

◆ HASH_REMOVE

◆ LRU_INSERT_HEAD

◆ LRU_INSERT_TAIL

◆ LRU_REMOVE

◆ OC_FLAG_INLRU

◆ OC_FLAG_INHASH

◆ OC_FLAG_SHARED

◆ OC_FLAG_NOTSYNC

◆ OC_FLAG_LAZYWRITE

◆ OC_FLAG_FORGET

Typedef Documentation

◆ oc_flags_t

◆ oc_hash_header_t

◆ oc_lru_header_t

◆ oc_object_t

◆ objects_cache_t

◆ oc_readf_t

◆ oc_writef_t

Function Documentation

◆ hash_get_s()

◆ lru_get_last_s()

◆ chCacheObjectInit()

◆ chCacheGetObject()

◆ chCacheReleaseObjectI()

◆ chCacheReadObject()

◆ chCacheWriteObject()

◆ chCacheReleaseObject()