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

FreeBSD Manual Pages

  
 
  

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

NAME
       pmemobj_alloc(),	pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(),
       pmemobj_zrealloc(),  pmemobj_strdup(),  pmemobj_wcsdup(),   pmemobj_al-
       loc_usable_size(),  POBJ_NEW(),	POBJ_ALLOC(),  POBJ_ZNEW(),  POBJ_ZAL-
       LOC(), POBJ_REALLOC(), POBJ_ZREALLOC(), POBJ_FREE() - non-transactional
       atomic allocations

SYNOPSIS
	      #include <libpmemobj.h>

	      typedef int (*pmemobj_constr)(**PMEMobjpool *pop,	void *ptr, void	*arg);
	      int pmemobj_alloc(PMEMobjpool *pop, PMEMoid *oidp, size_t	size,
		  uint64_t type_num, pmemobj_constr constructor, void *arg);
	      int pmemobj_xalloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
		  uint64_t type_num, uint64_t flags, pmemobj_constr constructor,
		  void *arg); (EXPERIMENTAL)
	      int pmemobj_zalloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
		  uint64_t type_num);
	      void pmemobj_free(PMEMoid	*oidp);
	      int pmemobj_realloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
		  uint64_t type_num);
	      int pmemobj_zrealloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
		  uint64_t type_num);
	      int pmemobj_strdup(PMEMobjpool *pop, PMEMoid *oidp, const	char *s,
		  uint64_t type_num);
	      int pmemobj_wcsdup(PMEMobjpool *pop, PMEMoid *oidp, const	wchar_t	*s,
		  uint64_t type_num);
	      size_t pmemobj_alloc_usable_size(PMEMoid oid);

	      POBJ_NEW(PMEMobjpool *pop, TOID *oidp, TYPE, pmemobj_constr constructor,
		  void *arg)
	      POBJ_ALLOC(PMEMobjpool *pop, TOID	*oidp, TYPE, size_t size,
		  pmemobj_constr constructor, void *arg)
	      POBJ_ZNEW(PMEMobjpool *pop, TOID *oidp, TYPE)
	      POBJ_ZALLOC(PMEMobjpool *pop, TOID *oidp,	TYPE, size_t size)
	      POBJ_REALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
	      POBJ_ZREALLOC(PMEMobjpool	*pop, TOID *oidp, TYPE,	size_t size)
	      POBJ_FREE(TOID *oidp)

DESCRIPTION
       Functions described in this document provide the	mechanism to allocate,
       resize  and  free  objects  from	 the  persistent  memory  pool	in   a
       thread-safe and fail-safe manner.  All the routines are atomic with re-
       spect to	other threads and any power-fail  interruptions.   If  any  of
       these  operations is torn by program failure or system crash, on	recov-
       ery they	are guaranteed to be entirely completed	or discarded,  leaving
       the  persistent memory heap and internal	object containers in a consis-
       tent state.

       All these functions can be used outside transactions.  Note that	opera-
       tions  performed	using the non-transactional API	are considered durable
       after completion, even if executed within an  open  transaction.	  Such
       non-transactional changes will not be rolled back if the	transaction is
       aborted or interrupted.

       The allocations are always aligned to a cache-line boundary.

       The pmemobj_constr type represents a constructor	for atomic  allocation
       from  the  persistent memory heap associated with memory	pool pop.  ptr
       is a pointer to the allocated memory area and arg is a user-defined ar-
       gument passed to	the constructor.

       The pmemobj_alloc() function allocates a	new object from	the persistent
       memory heap associated with memory pool pop.  The PMEMoid of the	 allo-
       cated  object is	stored in oidp.	 If oidp is NULL, then the newly allo-
       cated object may	be accessed only by iterating objects  in  the	object
       container  associated  with  the	 type number type_num, as described in
       POBJ_FOREACH(3).	 If oidp points	to a memory location from the  pmemobj
       heap,  oidp  is modified	atomically.  Before returning, pmemobj_alloc()
       calls the constructor function, passing the pool	handle pop, the	point-
       er  to  the newly allocated object in ptr, and the arg argument.	 It is
       guaranteed that the allocated object is either properly initialized, or
       if  the allocation is interrupted before	the constructor	completes, the
       memory space reserved for the object is reclaimed.   size  can  be  any
       non-zero	 value;	 however, due to internal padding and object metadata,
       the actual size of the allocation will differ from the  requested  size
       by  at  least  64 bytes.	 For this reason, making allocations of	a size
       less than 64 bytes is extremely inefficient and discouraged.  The allo-
       cated  object  is  added	 to  the  internal  container  associated with
       type_num.

       pmemobj_xalloc()	is equivalent to pmemobj_alloc(), but  with  an	 addi-
       tional flags argument that is a bitmask of the following	values:

       o POBJ_XALLOC_ZERO  -  zero  the	allocated object (equivalent of	pmemo-
	 bj_zalloc())

       o POBJ_CLASS_ID(class_id) - allocate  an	 object	 from  the  allocation
	 class class_id.  The class id cannot be 0.

       o POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified
	 by arena_id.  The arena must exist, otherwise,	the behavior is	 unde-
	 fined.	  If  arena_id	is equal 0, then arena assigned	to the current
	 thread	will be	used.

       The pmemobj_zalloc() function allocates a new zeroed  object  from  the
       persistent memory heap associated with memory pool pop.	The PMEMoid of
       the allocated object is stored in oidp.	If oidp	is NULL, then the new-
       ly  allocated  object  may be accessed only by iterating	objects	in the
       object container	associated with	the type number	type_num, as described
       in POBJ_FOREACH(3).  If oidp points to a	memory location	from the pmem-
       obj heap, oidp is modified atomically.  size can	be any non-zero	value;
       however,	 due  to internal padding and object metadata, the actual size
       of the allocation will differ from the requested	one  by	 at  least  64
       bytes.	For  this  reason,  making  allocations	of a size less than 64
       bytes is	extremely inefficient and discouraged.	The  allocated	object
       is added	to the internal	container associated with type_num.

       The pmemobj_free() function frees the memory space represented by oidp,
       which must have been allocated by a previous call  to  pmemobj_alloc(),
       pmemobj_xalloc(),  pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre-
       alloc().	 pmemobj_free()	provides the same semantics  as	 free(3),  but
       instead of operating on the process heap	supplied by the	system,	it op-
       erates on the persistent	memory heap.  If oidp is OID_NULL,  no	opera-
       tion  is	 performed.   If  oidp is NULL or if it	points to the root ob-
       ject's OID, the behavior	of pmemobj_free() is undefined.	 oidp  is  set
       to  OID_NULL after the memory is	freed.	If oidp	points to a memory lo-
       cation from the pmemobj heap, oidp is modified atomically.

       The pmemobj_realloc() function changes the size of  the	object	repre-
       sented  by  oidp	to size	bytes.	pmemobj_realloc() provides similar se-
       mantics to realloc(3), but operates on the persistent memory heap asso-
       ciated with memory pool pop.  The resized object	is also	added or moved
       to the internal container associated with type  number  type_num.   The
       contents	will be	unchanged in the range from the	start of the region up
       to the minimum of the old and new sizes.	 If the	 new  size  is	larger
       than  the  old size, the	added memory will not be initialized.  If oidp
       is OID_NULL, then the call is equivalent	 to  pmemobj_alloc(pop,	 size,
       type_num).   If	size  is equal to zero,	and oidp is not	OID_NULL, then
       the call	is equivalent to pmemobj_free(oid).  Unless oidp is  OID_NULL,
       it  must	 have  been  allocated	by an earlier call to pmemobj_alloc(),
       pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or  pmemobj_zre-
       alloc().	  Note	that the object	handle value may change	as a result of
       reallocation.  If the object was	moved, the memory space	represented by
       oid is reclaimed.  If oidp points to a memory location from the pmemobj
       heap, oidp is modified atomically.  If oidp is NULL or if it points  to
       the root	object's OID, the behavior of pmemobj_realloc()	is undefined.

       pmemobj_zrealloc()  is  equivalent to pmemobj_realloc(),	except that if
       the new size is larger than the old size, the added memory will be  ze-
       roed.

       The  pmemobj_strdup()  function stores a	handle to a new	object in oidp
       which is	a duplicate of the string s.   pmemobj_strdup()	 provides  the
       same semantics as strdup(3), but	operates on the	persistent memory heap
       associated with memory pool pop.	 If oidp is NULL, then the newly allo-
       cated  object  may  be accessed only by iterating objects in the	object
       container  associated  with  type  number  type_num,  as	 described  in
       POBJ_FOREACH(3).	  If oidp points to a memory location from the pmemobj
       heap, oidp is modified atomically.  The allocated string	object is also
       added  to  the internal container associated with type number type_num.
       Memory for the new string is obtained with pmemobj_alloc(), on the giv-
       en memory pool, and can be freed	with pmemobj_free() on the same	memory
       pool.

       pmemobj_wcsdup()	is equivalent to pmemobj_strdup(), but operates	 on  a
       wide  character	string	(wchar_t)  rather  than	 a  standard character
       string.

       The pmemobj_alloc_usable_size() function	provides the same semantics as
       malloc_usable_size(3),  but instead of the process heap supplied	by the
       system, it operates on the persistent memory heap.

       The POBJ_NEW() macro is a wrapper around	the pmemobj_alloc()  function.
       Instead of taking a pointer to PMEMoid, it takes	a pointer to the typed
       OID of type name	TYPE, and passes the size and  type  number  from  the
       typed OID to pmemobj_alloc().

       The  POBJ_ALLOC()  macro	is equivalent to POBJ_NEW, except that instead
       of using	the size of the	typed OID, passes size to pmemobj_alloc().

       The POBJ_ZNEW() macro is	a wrapper around  the  pmemobj_zalloc()	 func-
       tion.   Instead	of  taking a pointer to	PMEMoid, it takes a pointer to
       the typed OID of	type name TYPE,	and passes the size  and  type	number
       from the	typed OID to pmemobj_zalloc().

       The POBJ_ZALLOC() macro is equivalent to	POBJ_ZNEW, except that instead
       of using	the size of the	typed OID, passes size to pmemobj_zalloc().

       The POBJ_REALLOC() macro	is  a  wrapper	around	the  pmemobj_realloc()
       function.   Instead  of taking a	pointer	to PMEMoid, it takes a pointer
       to the typed OID	of type	name TYPE, and passes the type number from the
       typed OID to pmemobj_realloc().

       The  POBJ_ZREALLOC()  macro  is a wrapper around	the pmemobj_zrealloc()
       function.  Instead of taking a pointer to PMEMoid, it takes  a  pointer
       to the typed OID	of type	name TYPE, and passes the type number from the
       typed OID to pmemobj_zrealloc().

       The POBJ_FREE() macro is	a wrapper around the  pmemobj_free()  function
       which takes a pointer to	the typed OID instead of to PMEMoid.

RETURN VALUE
       On  success,  pmemobj_alloc()  and pmemobj_xalloc return	0.  If oidp is
       not NULL, the PMEMoid of	the newly allocated object is stored in	 oidp.
       If the allocation fails,	-1 is returned and errno is set	appropriately.
       If the constructor returns a non-zero value,  the  allocation  is  can-
       celed,  -1  is returned,	and errno is set to ECANCELED.	If size	equals
       0, or the flags for pmemobj_xalloc are invalid, -1 is  returned,	 errno
       is set to EINVAL, and oidp is left untouched.

       On success, pmemobj_zalloc() returns 0.	If oidp	is not NULL, the PMEM-
       oid of the newly	allocated object is stored in oidp.  If	the allocation
       fails,  it  returns -1 and sets errno appropriately.  If	size equals 0,
       it returns -1, sets errno to EINVAL, and	leaves oidp untouched.

       The pmemobj_free() function returns no value.

       On success, pmemobj_realloc() and pmemobj_zrealloc() return 0  and  up-
       date  oidp if necessary.	 On error, they	return -1 and set errno	appro-
       priately.

       On success, pmemobj_strdup() and	pmemobj_wcsdup() return	0.  If oidp is
       not  NULL,  the	PMEMoid	 of  the duplicated string object is stored in
       oidp.  If s is NULL, they return	-1, set	errno  to  EINVAL,  and	 leave
       oidp  untouched.	  On other errors, they	return -1 and set errno	appro-
       priately.

       The pmemobj_alloc_usable_size() function	returns	the number  of	usable
       bytes in	the object represented by oid.	If oid is OID_NULL, it returns
       0.

SEE ALSO
       free(3),	POBJ_FOREACH(3), realloc(3), strdup(3),	 wcsdup(3),  libpmemo-
       bj(7) and <http://pmem.io>

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

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | SEE ALSO

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

home | help