Lockers

Data Structures
struct	m0_lockers_type
struct	m0_lockers

Macros
#define	M0_LOCKERS_DECLARE(scope, name, max)   M0_LOCKERS__DECLARE(scope, name, name, max)
#define	M0_LOCKERS__DECLARE(scope, name, amb, max)
#define	M0_LOCKERS_DEFINE(scope, name, field)   M0_LOCKERS__DEFINE(scope, name, name, field)
#define	M0_LOCKERS__DEFINE(scope, name, amb, field)

Functions
static bool	key_is_valid (const struct m0_lockers_type *lt, int key)
M0_INTERNAL void	m0_lockers_init (const struct m0_lockers_type *lt, struct m0_lockers *lockers)
M0_INTERNAL int	m0_lockers_allot (struct m0_lockers_type *lt)
M0_INTERNAL void	m0_lockers_free (struct m0_lockers_type *lt, int key)
M0_INTERNAL void	m0_lockers_set (const struct m0_lockers_type *lt, struct m0_lockers *lockers, uint32_t key, void *data)
M0_INTERNAL void *	m0_lockers_get (const struct m0_lockers_type *lt, const struct m0_lockers *lockers, uint32_t key)
M0_INTERNAL void	m0_lockers_clear (const struct m0_lockers_type *lt, struct m0_lockers *lockers, uint32_t key)
M0_INTERNAL bool	m0_lockers_is_empty (const struct m0_lockers_type *lt, const struct m0_lockers *lockers, uint32_t key)
M0_INTERNAL void	m0_lockers_fini (struct m0_lockers_type *lt, struct m0_lockers *lockers)

Detailed Description

Lockers module provides an interface to support storage of private pointers in parent structures. This allows not only for efficient sharing of data with others but also removes duplication of such interfaces. To describe a typical usage pattern, consider one wants a locker for 32 objects in object of type foo.

Following things have to be done:

• Declare a locker type by, M0_LOCKERS_DECLARE(scope, foo, 32) This will generate a structure of type foo_lockers and declarations for functions to manipulate foo_lockers. It is required that a structure of type foo must be present in the source.
• embed foo_lockers in struct foo

struct foo {
      ...
      struct foo_lockers lockers;
      ...
};

• Next, define a locker type by M0_LOCKERS_DEFINE(scope, foo, lockers)

Now to use this locker following interfaces can be used:

• foo_lockers_allot - Returns new key to access stored data.
• foo_lockers_set - Stores provided data against provided key.
• foo_lockers_get - Locates and returns data corresponding to the provided key.
• foo_lockers_clear - Clears the data stored at given key.
• foo_lockers_is_empty - Checks whether a data is stored at given key.

Lockers module does not provide any support against concurrency and validation of data stored at a given key, it is the responsibility of the invoker to take care of these aspects.

Please refer to unit test for understanding the nitty-gritty of lockers.

Macro Definition Documentation

M0_LOCKERS__DECLARE

#define M0_LOCKERS__DECLARE	(		scope,
			name,
			amb,
			max
	)

Value:

struct name;                                                            \
                                                                        \
enum { M0_LOCKERS_ ## name ## _max = (max) };                           \
                                                                        \
struct name ## _lockers {                                               \
        struct m0_lockers __base;                                       \
        void             *__slots[(max)];                               \
};                                                                      \
									\
M0_BASSERT(offsetof(struct name ## _lockers, __slots[0]) ==             \
           offsetof(struct m0_lockers, loc_slots[0]));                  \
                                                                        \
scope void name ## _lockers_init(struct amb *par);                      \
scope void name ## _lockers_fini(struct amb *par);                      \
scope int name ## _lockers_allot(void);                         \
scope void name ## _lockers_free(int key);                              \
scope void name ## _lockers_set(struct amb *par, int key, void *data);  \
scope void * name ## _lockers_get(const struct amb *par, int key);      \
scope void name ## _lockers_clear(struct amb *par, int key);            \
scope bool name ## _lockers_is_empty(const struct amb *par, int key)

Definition at line 90 of file lockers.h.

M0_LOCKERS__DEFINE

#define M0_LOCKERS__DEFINE	(		scope,
			name,
			amb,
			field
	)

Definition at line 166 of file lockers.h.

M0_LOCKERS_DECLARE

#define M0_LOCKERS_DECLARE	(		scope,
			name,
			max
	)		M0_LOCKERS__DECLARE(scope, name, name, max)

Definition at line 87 of file lockers.h.

M0_LOCKERS_DEFINE

#define M0_LOCKERS_DEFINE	(		scope,
			name,
			field
	)		M0_LOCKERS__DEFINE(scope, name, name, field)

Definition at line 163 of file lockers.h.

Function Documentation

key_is_valid()

static bool key_is_valid ( const struct m0_lockers_type *  lt, int  key  )

static

Definition at line 101 of file lockers.c.

Here is the caller graph for this function:

m0_lockers_allot()

M0_INTERNAL int m0_lockers_allot

(

struct m0_lockers_type *

lt

)

Allots a new key of type lt

Precondition

lt->lot_count < lt->lot_max

Definition at line 44 of file lockers.c.

m0_lockers_clear()

M0_INTERNAL void m0_lockers_clear	(	const struct m0_lockers_type *	lt,
		struct m0_lockers *	lockers,
		uint32_t	key
	)

Clears the value stored in a locker

Postcondition

m0_lockers_is_empty(locker, key)

Definition at line 80 of file lockers.c.

Here is the call graph for this function:

m0_lockers_fini()

M0_INTERNAL void m0_lockers_fini	(	struct m0_lockers_type *	lt,
		struct m0_lockers *	lockers
	)

Definition at line 96 of file lockers.c.

m0_lockers_free()

M0_INTERNAL void m0_lockers_free	(	struct m0_lockers_type *	lt,
		int	key
	)

Frees a key of type lt

Precondition

lt->lot_count < lt->lot_max

Definition at line 57 of file lockers.c.

Here is the call graph for this function:

m0_lockers_get()

M0_INTERNAL void * m0_lockers_get	(	const struct m0_lockers_type *	lt,
		const struct m0_lockers *	lockers,
		uint32_t	key
	)

Retrieves a value stored in locker

Precondition

!m0_lockers_is_empty(locker, key)

Definition at line 72 of file lockers.c.

Here is the call graph for this function:

m0_lockers_init()

M0_INTERNAL void m0_lockers_init	(	const struct m0_lockers_type *	lt,
		struct m0_lockers *	lockers
	)

Definition at line 37 of file lockers.c.

m0_lockers_is_empty()

M0_INTERNAL bool m0_lockers_is_empty	(	const struct m0_lockers_type *	lt,
		const struct m0_lockers *	lockers,
		uint32_t	key
	)

Definition at line 88 of file lockers.c.

Here is the call graph for this function:

m0_lockers_set()

M0_INTERNAL void m0_lockers_set	(	const struct m0_lockers_type *	lt,
		struct m0_lockers *	lockers,
		uint32_t	key,
		void *	data
	)

Stores a value in locker

Postcondition

!m0_lockers_is_empty(locker, key) && m0_lockers_get(locker, key) == data

Definition at line 63 of file lockers.c.

Here is the call graph for this function: