Provided by: libpmemobj-dev_1.13.1-1.1ubuntu2_amd64 bug

NAME

       pmemobj_alloc(),     pmemobj_xalloc(),     pmemobj_zalloc(),    pmemobj_realloc(),    pmemobj_zrealloc(),
       pmemobj_strdup(),   pmemobj_wcsdup(),    pmemobj_alloc_usable_size(),    pmemobj_defrag(),    POBJ_NEW(),
       POBJ_ALLOC(),   POBJ_ZNEW(),   POBJ_ZALLOC(),   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);
              int pmemobj_defrag(PMEMobjpool *pop, PMEMoid **oidv, size_t oidcnt,
                  struct pobj_defrag_result *result);

              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 respect
       to other threads and any power-fail interruptions.  If any of these operations is torn by program failure
       or  system  crash,  on  recovery  they  are guaranteed to be entirely completed or discarded, leaving the
       persistent memory heap and internal object containers in a consistent state.

       All these functions should be used outside transactions.  If executed within an open transaction they are
       considered  durable  immediately  after completion.  Changes made with these functions will not be rolled
       back if the transaction is aborted or interrupted.  They have no information about other changes made  by
       transactional  API,  so if the same data is modified in a single transaction using transactional and then
       non-transactional API, transaction abort will likely corrupt the data.

       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
       argument 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 allocated object is stored in oidp.  If oidp is NULL, then the newly
       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
       pmemobj heap, oidp is modified atomically.   Before  returning,  pmemobj_alloc()  calls  the  constructor
       function,  passing  the  pool  handle  pop, the pointer 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  allocated
       object is added to the internal container associated with type_num.

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

       • POBJ_XALLOC_ZERO - zero the allocated object (equivalent of pmemobj_zalloc())

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

       • POBJ_ARENA_ID(arena_id)  -  allocate  an  object  from the arena specified by arena_id.  The arena must
         exist, otherwise, the behavior is undefined.  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
       newly  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
       pmemobj  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_zrealloc().   pmemobj_free()  provides the same semantics as free(3), but instead of operating on
       the process heap supplied by the system, it operates on the persistent memory heap.  If oidp is OID_NULL,
       no  operation  is  performed.   If oidp is NULL or if it points to the root object’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 location from the pmemobj heap, oidp is modified atomically.

       The  pmemobj_realloc()  function  changes  the  size  of  the  object  represented by oidp to size bytes.
       pmemobj_realloc() provides similar semantics to realloc(3), but operates on the  persistent  memory  heap
       associated  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_zrealloc().  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 zeroed.

       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 allocated 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 given 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() 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_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.

       The pmemobj_defrag() function performs defragmentation on the  objects  provided  through  the  array  of
       pointers to PMEMoids oidv with size oidcnt.  If an object from the provided array is selected to be moved
       to a new location in the heap, it is reallocated and all provided pointers to that object are  atomically
       updated.   To maintain data structure consistency, applications should always provide all pointers for an
       object to pmemobj_defrag method.  This ensures that, even in the presence of failures,  all  pointers  to
       the  object  will  either point to the old or a new location.  All objects and pointers to objects should
       belong to the pool pop or, in case of pointers, can also  reside  in  volatile  memory.   Defragmentation
       across  pools is not supported.  Objects in the array that are OID_NULL are skipped over and no operation
       is performed on them.  All other objects must have been allocated by an earlier call to  pmemobj_alloc(),
       pmemobj_xalloc(),    pmemobj_zalloc(),   pmemobj_realloc(),   pmemobj_zrealloc(),   pmemobj_strdup()   or
       pmemobj_wcsdup().  The result variable is an instance of struct pobj_defrag_result and, if not NULL,  can
       be  used  to  read  total,  the number of objects found that were processed, and relocated, the number of
       objects that were relocated during defragmentation.  These variables are always initialized  and  can  be
       non-zero,  even if the return value of pmemobj_defrag() indicated a failure.  This is because the failure
       might have occurred after some objects were already processed.

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 canceled, -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 PMEMoid 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 update oidp if  necessary.   On  error,
       they return -1 and set errno appropriately.

       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 appropriately.

       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.

       On success, pmemobj_defrag() returns 0.  If defragmentation was unsuccessful or only partially successful
       (i.e. if it was aborted halfway through due to lack of resources), -1 is returned.

SEE ALSO

       free(3), POBJ_FOREACH(3), realloc(3), strdup(3), wcsdup(3), libpmemobj(7) and <https://pmem.io>