NAME

       pmemobj_list_insert(),           pmemobj_list_insert_new(),           pmemobj_list_move(),
       pmemobj_list_remove() - non-transactional persistent atomic lists functions

SYNOPSIS

              #include <libpmemobj.h>

              int pmemobj_list_insert(PMEMobjpool *pop, size_t pe_offset, void *head,
                  PMEMoid dest, int before, PMEMoid oid);

              PMEMoid pmemobj_list_insert_new(PMEMobjpool *pop, size_t pe_offset,
                  void *head, PMEMoid dest, int before, size_t size,
                  uint64_t type_num, pmemobj_constr constructor, void arg);

              int pmemobj_list_move(PMEMobjpool *pop,
                  size_t pe_old_offset, void *head_old,
                  size_t pe_new_offset, void *head_new,
                  PMEMoid dest, int before, PMEMoid oid);

              int pmemobj_list_remove(PMEMobjpool *pop, size_t pe_offset,
                  void *head, PMEMoid oid, int free);

DESCRIPTION

       In addition to the container  operations  on  internal  object  collections  described  in
       pmemobj_first(3),  libpmemobj(7) provides a mechanism for organizing persistent objects in
       user-defined, persistent, atomic, circular, doubly-linked lists.   All  the  routines  and
       macros  operating on the persistent lists provide atomicity with respect to any power-fail
       interruptions.  If any of those operations is torn by program failure or system crash,  on
       recovery  they  are  guaranteed  to be entirely completed or discarded, leaving the lists,
       persistent memory heap and internal object containers in a consistent state.

       The persistent atomic circular doubly linked lists support the following functionality:

       • Insertion of an object at the head of the list, or at the end of the list.

       • Insertion of an object before or after any element in the list.

       • Atomic allocation and insertion of a new object at the head of the list, or at  the  end
         of the list.

       • Atomic allocation and insertion of a new object before or after any element in the list.

       • Atomic moving of an element from one list to the specific location on another list.

       • Removal of any object in the list.

       • Atomic removal and freeing of any object in the list.

       • Forward or backward traversal through the list.

       A  list  is  headed  by  a  list_head  structure containing the object handle of the first
       element on the list.  The elements are doubly linked so that an arbitrary element  can  be
       removed  without  the  need  to  traverse the list.  New elements can be added to the list
       before or after an existing element, at the head of the list, or at the tail of the  list.
       A list may be traversed in either direction.

       The  user-defined  structure  of each element must contain a field of type list_entry that
       holds the object handles to the previous and next element on the list.  Both the list_head
       and the list_entry structures are declared in <libpmemobj.h>.

       The  functions below are intended to be used outside transactions - transactional variants
       are described in manpages to functions mentioned at TRANSACTIONAL OBJECT  MANIPULATION  in
       libpmemobj(7).   Note  that  operations  performed  using  this  non-transactional API are
       independent from their transactional counterparts.  If any  non-transactional  allocations
       or  list  manipulations  are performed within an open transaction, the changes will not be
       rolled back if such a transaction is aborted or interrupted.

       The list insertion and move functions use a common set of arguments  to  define  where  an
       object  will be inserted into the list.  dest identifies the element before or after which
       the object will be inserted, or, if dest is OID_NULL, indicates that the object should  be
       inserted  at  the  head  or  tail of the list.  before determines where the object will be
       inserted:

       • POBJ_LIST_DEST_BEFORE - insert the element before the existing element dest

       • POBJ_LIST_DEST_AFTER - insert the element after the existing element dest

       • POBJ_LIST_DEST_HEAD - when dest is OID_NULL, insert the element at the head of the list

       • POBJ_LIST_DEST_TAIL - when dest is OID_NULL, insert the element at the tail of the list

         NOTE:  Earlier  versions  of  libpmemobj(7)  do  not  define  POBJ_LIST_DEST_BEFORE  and
         POBJ_LIST_DEST_AFTER.  Use 1 for before, and 0 for after.

       The  pmemobj_list_insert()  function  inserts the element represented by object handle oid
       into the list referenced by head,  at  the  location  specified  by  dest  and  before  as
       described  above.   pe_offset  specifies  the  offset  of  the structure that connects the
       elements in the list.  All the handles head, dest and oid must point to objects  allocated
       from memory pool pop.  head and oid cannot be OID_NULL.

       The pmemobj_list_insert_new() function atomically allocates a new object of given size and
       type type_num and inserts it into the list referenced by head at the location specified by
       dest  and before as described above.  pe_offset specifies the offset of the structure that
       connects the elements in the list.  The handles  head  and  dest  must  point  to  objects
       allocated  from  memory  pool  pop.  Before returning, pmemobj_list_insert_new() calls the
       constructor function, passing the pool handle pop, the  pointer  to  the  newly  allocated
       object  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.  head cannot be
       OID_NULL.  The allocated object is also added to the internal  container  associated  with
       type_num, as described in POBJ_FOREACH(3).

       The  pmemobj_list_move()  function  moves the object represented by object handle oid from
       the list referenced by head_old to the list referenced by head_new, inserting  it  at  the
       location specified by dest and before as described above.  pe_old_offset and pe_new_offset
       specify the offsets of the structures that connect the elements in the old and new  lists,
       respectively.   All  the  handles  head_old,  head_new, dest and oid must point to objects
       allocated from memory pool pop.  head_old, head_new and oid cannot be OID_NULL.

       The pmemobj_list_remove() function removes the object represented  by  object  handle  oid
       from  the  list  referenced  by head.  If free is set, it also removes the object from the
       internal object container and frees the associated memory space.  pe_offset specifies  the
       offset  of  the  structure that connects the elements in the list.  Both head and oid must
       point to objects allocated from memory pool pop and cannot be OID_NULL.

RETURN VALUE

       On success, pmemobj_list_insert(), pmemobj_list_remove() and pmemobj_list_move() return 0.
       On error, they return -1 and set errno appropriately.

       On  success, pmemobj_list_insert_new() returns a handle to the newly allocated object.  If
       the constructor returns a non-zero value, the allocation is canceled, -1 is returned,  and
       errno  is  set  to  ECANCELED.   On  other  errors,  OID_NULL is returned and errno is set
       appropriately.

SEE ALSO

       pmemobj_first(3), POBJ_FOREACH(3), libpmemobj(7) and <http://pmem.io>