Branded objects

Data Structures
struct	m0_bob_type

Macros
#define	MAGIX(bt, bob)   ((uint64_t *)(bob + bt->bt_magix_offset))
#define	M0_BOB_DEFINE(scope, bob_type, type)
#define	M0_BOB_DECLARE(scope, type)
#define	bob_of(ptr, type, field, bt)

Functions
static bool	bob_type_invariant (const struct m0_bob_type *bt)
M0_INTERNAL void	m0_bob_type_tlist_init (struct m0_bob_type *bt, const struct m0_tl_descr *td)
M0_INTERNAL void	m0_bob_init (const struct m0_bob_type *bt, void *bob)
M0_INTERNAL void	m0_bob_fini (const struct m0_bob_type *bt, void *bob)
M0_INTERNAL bool	m0_bob_check (const struct m0_bob_type *bt, const void *bob)

Variables
struct m0_bob_type	M0_XCA_DOMAIN

Detailed Description

Branded object (bob) module provides support for a simple run-time type identification.

A branded object is any memory structure containing magic field at a known offset. A branded object type (m0_bob_type) specifies the offset and the required magic value field, together with an optional check function. m0_bob_check() function returns true iff the memory structure given to it as a parameter has the required magic value and satisfies the optional check.

For flexibility branded objects are not represented by a special data-type. Instead m0_bob_check() takes a void pointer.

A couple of helper functions are provided to initialize m0_bob_type:

- m0_bob_type_tlist_init(): used when branded object is used as a typed
  list link, @see lib/tlist.h.

- m0_xcode_bob_type_init(): used in case where branded object type has an
  xcode representation, @see xcode/xcode.h. This function is defined in
  xcode.h to avoid introducing dependencies.

A user is explicitly allowed to initialize m0_bob_type instance manually and to set up the optional check function (m0_bob_type::bt_check()) either before or after using these helpers.

Macro Definition Documentation

bob_of

#define bob_of	(		ptr,
			type,
			field,
			bt
	)

Value:

({                                                                      \
        void *__ptr = (void *)(ptr);                                    \
        type *__amb;                                                    \
									\
	M0_ASSERT(__ptr != NULL);                                      \
        __amb = container_of(__ptr, type, field);                       \
									\
	M0_ASSERT_INFO(m0_bob_check(bt, __amb),                        \
                "%s.%s [%p->%p (%s)] got: %" PRIx64 " want: %" PRIx64   \
                " check: %i.", (bt)->bt_name, #field, __ptr, __amb, #type, \
                *((uint64_t *)(((void *)__amb) + (bt)->bt_magix_offset)), \
                (bt)->bt_magix,                                 \
                (bt)->bt_check != NULL ? (bt)->bt_check(__amb) : -1);   \
        __amb;                                                          \
})

A safer version of container_of().

Given a pointer (ptr) returns an ambient object of given type of which ptr is a field. Ambient object has bob type "bt".

Definition at line 140 of file bob.h.

M0_BOB_DECLARE

#define M0_BOB_DECLARE	(		scope,
			type
	)

Value:

scope void type ## _bob_init(struct type *bob);         \
scope void type ## _bob_fini(struct type *bob);         \
scope bool type ## _bob_check(const struct type *bob)

Definition at line 129 of file bob.h.

M0_BOB_DEFINE

#define M0_BOB_DEFINE	(		scope,
			bob_type,
			type
	)

Value:

scope void type ## _bob_init(struct type *bob)                  \
{                                                               \
        m0_bob_init(bob_type, bob);                             \
}                                                               \
                                                                \
scope void type ## _bob_fini(struct type *bob)                  \
{                                                               \
        m0_bob_fini(bob_type, bob);                             \
}                                                               \
                                                                \
scope M0_UNUSED bool type ## _bob_check(const struct type *bob) \
{                                                               \
        return m0_bob_check(bob_type, bob);                     \
}                                                               \
                                                                \
struct __ ## type ## _semicolon_catcher

Produces a type-safe versions of m0_bob_init(), m0_bob_fini() and m0_bob_check(), taking branded object of a given type.

Definition at line 111 of file bob.h.

MAGIX

#define MAGIX	(		bt,
			bob
	)		((uint64_t *)(bob + bt->bt_magix_offset))

Returns the address of the magic field.

Macro is used instead of inline function so that constness of the result depends on the constness of "bob" argument.

Definition at line 59 of file bob.c.

Function Documentation

bob_type_invariant()

static bool bob_type_invariant ( const struct m0_bob_type *  bt )

static

Definition at line 34 of file bob.c.

Here is the caller graph for this function:

m0_bob_check()

M0_INTERNAL bool m0_bob_check	(	const struct m0_bob_type *	bt,
		const void *	bob
	)

Returns true iff a branded object has the required magic value and check function, if any, returns true.

Definition at line 74 of file bob.c.

Here is the caller graph for this function:

m0_bob_fini()

M0_INTERNAL void m0_bob_fini	(	const struct m0_bob_type *	bt,
		void *	bob
	)

Finalizes a branded object, by re-setting the magic field to 0.

Definition at line 68 of file bob.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_bob_init()

M0_INTERNAL void m0_bob_init	(	const struct m0_bob_type *	bt,
		void *	bob
	)

Initializes a branded object, by setting the magic field.

Definition at line 61 of file bob.c.

Here is the call graph for this function:

Here is the caller graph for this function:

m0_bob_type_tlist_init()

M0_INTERNAL void m0_bob_type_tlist_init	(	struct m0_bob_type *	bt,
		const struct m0_tl_descr *	td
	)

Partially initializes a branded object type from a typed list descriptor.

Definition at line 41 of file bob.c.

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

M0_XCA_DOMAIN

struct m0_bob_type M0_XCA_DOMAIN