Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
OID_IS_NULL(3)		   PMDK	Programmer's Manual		OID_IS_NULL(3)

NAME
       OID_IS_NULL(),  OID_EQUALS(),  pmemobj_direct(),	 pmemobj_oid(),	pmemo-
       bj_type_num(), pmemobj_pool_by_oid(), pmemobj_pool_by_ptr() - functions
       that allow mapping operations between object addresses, object handles,
       oids or type numbers

SYNOPSIS
	      #include <libpmemobj.h>

	      OID_IS_NULL(PMEMoid oid)
	      OID_EQUALS(PMEMoid lhs, PMEMoid rhs)

	      void *pmemobj_direct(PMEMoid oid);
	      PMEMoid pmemobj_oid(const	void *addr);
	      uint64_t pmemobj_type_num(PMEMoid	oid);
	      PMEMobjpool *pmemobj_pool_by_oid(PMEMoid oid);
	      PMEMobjpool *pmemobj_pool_by_ptr(const void *addr);
	      void *pmemobj_volatile(PMEMobjpool *pop, struct pmemvlt *vlt,
		  size_t size, void *ptr,
		  int (*constr)(void *ptr, void	*arg), void *arg); (EXPERIMENTAL)

DESCRIPTION
       Each object stored in a persistent memory pool is represented by	an ob-
       ject  handle  of	 type PMEMoid.	In practice, such a handle is a	unique
       Object IDentifier (OID) of global scope,	which means that  two  objects
       from  different	pools  will  never  have  the  same  OID.  The special
       OID_NULL	macro defines a	NULL-like handle that does not	represent  any
       object.	 The  size  of	a  single object is limited by PMEMOBJ_MAX_AL-
       LOC_SIZE.  Thus an allocation with a requested size greater  than  this
       value will fail.

       An  OID cannot be used as a direct pointer to an	object.	 Each time the
       program attempts	to read	or write object	data, it must obtain the  cur-
       rent memory address of the object by converting its OID into a pointer.

       In  contrast to the memory address, the OID value for given object does
       not change during the life of an	object (except for realloc),  and  re-
       mains  valid after closing and reopening	the pool.  For this reason, if
       an object contains a reference to another persistent object, for	 exam-
       ple,  to	build some kind	of a linked data structure, the	reference must
       be an OID and not a memory address.

       pmemobj_direct()	returns	a pointer to the PMEMoid  object  with	handle
       oid.

       pmemobj_oid()  returns a	PMEMoid	handle to the object pointed to	by ad-
       dr.

       pmemobj_type_num() returns the type number of the PMEMoid  object  with
       handle oid.

       pmemobj_pool_by_oid()  returns  a  PMEMobjpool* handle to the pool con-
       taining the PMEMoid object with handle oid.

       pmemobj_pool_by_ptr() returns a PMEMobjpool* handle to  the  pool  con-
       taining the address addr.

       At  the	time  of  allocation (or reallocation),	each object may	be as-
       signed a	number representing its	type.  Such a type number may be  used
       to  arrange  the	 persistent objects based on their actual user-defined
       structure type, thus facilitating implementation	of a  simple  run-time
       type  safety mechanism.	This also allows iterating through all the ob-
       jects of	a given	type that are stored in	the  persistent	 memory	 pool.
       See pmemobj_first(3) for	more information.

       The OID_IS_NULL() macro checks if PMEMoid represents a NULL object.

       The OID_EQUALS()	macro compares two PMEMoid objects.

       For  special  cases  where  volatile  (transient)  variables need to be
       stored on persistent memory, there's a  mechanism  composed  of	struct
       pmemvlt	type  and  pmemobj_volatile() function.	 To use	it, the	struct
       pmemvlt needs to	be placed in the neighborhood of  transient  data  re-
       gion.   The  PMEMvlt macro can be used to construct such	a region.  The
       struct pmemvlt must be zeroed prior to use.  This can be	easily done in
       object  constructor  or	in a transaction directly after	an allocation.
       When the	pmemobj_volatile() function is called on a struct pmemvlt,  it
       will return the pointer to the data and it will ensure that the provid-
       ed constructor function is called exactly once in the current  instance
       of the pmemobj pool.  The constructor is	called with the	ptr pointer to
       the data, and this function will	return the same	pointer	 if  the  con-
       structor	returns	0, otherwise NULL is returned.	The size argument must
       accurately describe the total size of the volatile memory  region  that
       will  be	 accessed.  Calling pmemobj_volatile() on the same region with
       different sizes is undefined behavior.  For this	mechanism to be	effec-
       tive, all accesses to transient variables must go through it, otherwise
       there's a risk of the constructor not being called on the  first	 load.
       Maintaining  transient state on persistent memory is challenging	due to
       difficulties with dynamic resources acquisition and subsequent resource
       release.	 For example, one needs	to consider what happens with volatile
       state of	an object which	is being freed inside of a transaction,	 espe-
       cially  with  regards  to  the possibility of an	abort.	It's generally
       recommended to entirely separate	the persistent and  transient  states,
       and  when  it's	not possible, to only store types which	do not require
       lifecycle management (i.e., primitive types)  inside  of	 volatile  re-
       gions.

RETURN VALUE
       The  pmemobj_direct()  function	returns	a pointer to the object	repre-
       sented by oid.  If oid is OID_NULL, pmemobj_direct() returns NULL.

       The pmemobj_oid() function returns  a  PMEMoid  handle  to  the	object
       pointed	to  by	addr.	If  addr  is  not  from	within a pmemobj pool,
       OID_NULL	is returned.  If addr is not the start of an object (does  not
       point  to  the  beginning of a valid allocation), the resulting PMEMoid
       can be safely used only with:

       o pmemobj_pool_by_oid()

       o pmemobj_direct()

       o pmemobj_tx_add_range(3)

       The pmemobj_type_num() function returns the type	number of  the	object
       represented by oid.

       The  pmemobj_pool_by_oid()  function  returns a handle to the pool that
       contains	the object represented by oid.	If the the pool	is not open or
       oid is OID_NULL,	pmemobj_pool_by_oid() returns NULL.

       The  pmemobj_pool_by_ptr()  function  returns a handle to the pool that
       contains	the address, or	NULL if	the address does  not  belong  to  any
       open pool.

NOTES
       For  performance	 reasons,  on  Linux  and FreeBSD the pmemobj_direct()
       function	is inlined by default.	To  use	 the  non-inlined  variant  of
       pmemobj_direct(),  define  PMEMOBJ_DIRECT_NON_INLINE  prior to the #in-
       clude of	<libpmemobj.h>,	either with #define or with the	-D  option  to
       the compiler.

EXAMPLES
       The following code shows	how to store transient variables on persistent
       memory.

	      struct my_data {
		  PMEMvlt(uint64_t) foo;
		  uint64_t bar;
	      };

	      int
	      my_data_constructor(void *ptr, void *arg)
	      {
		  uint64_t *foo	= ptr;
		  *foo = 0;

		  return 0;
	      }

	      PMEMobjpool *pop = ...;

	      struct my_data *data = D_RW(...);

	      uint64_t *foo = pmemobj_volatile(pop, &data->foo.vlt, &data->foo.value,
		  my_data_constructor, NULL);

	      assert(*foo == 0);

SEE ALSO
       libpmemobj(7) and <http://pmem.io>

PMDK - pmemobj API version 2.3	  2019-07-10			OID_IS_NULL(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | NOTES | EXAMPLES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=oid_is_null&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help