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

FreeBSD Manual Pages

  
 
  

home | help
LIBPMEMOBJ(7)		   PMDK	Programmer's Manual		 LIBPMEMOBJ(7)

NAME
       libpmemobj - persistent memory transactional object store

SYNOPSIS
	      #include <libpmemobj.h>
	      cc -std=gnu99 ...	-lpmemobj -lpmem

   Library API versioning:
	      const char *pmemobj_check_version(
		  unsigned major_required,
		  unsigned minor_required);

   Managing library behavior:
	      void pmemobj_set_funcs(
		  void *(*malloc_func)(size_t size),
		  void (*free_func)(void *ptr),
		  void *(*realloc_func)(void *ptr, size_t size),
		  char *(*strdup_func)(const char *s));

   Error handling:
	      const char *pmemobj_errormsg(void);

   Other library functions:
       A description of	other libpmemobj functions can be found	on the follow-
       ing manual pages:

       o control and statistics: pmemobj_ctl_get(3)

       o create, open, close and validate: pmemobj_open(3)

       o low-level memory manipulation:	pmemobj_memcpy_persist(3)

       o locking: pmemobj_mutex_zero(3)

       o persistent object identifier: OID_IS_NULL(3)

       o type-safety: TOID_DECLARE(3)

       o layout	declaration: POBJ_LAYOUT_BEGIN(3)

       o non-transactional atomic allocations: pmemobj_alloc(3)

       o root object management: pmemobj_root(3)

       o object	containers: pmemobj_first(3)

       o non-transactional  persistent	atomic	circular  doubly-linked	 list:
	 pmemobj_list_insert(3), POBJ_LIST_HEAD(3)

       o transactional	 object	  manipulation:	  pmemobj_tx_begin(3),	pmemo-
	 bj_tx_add_range(3), pmemobj_tx_alloc(3)

       o delayed atomicity actions: pmemobj_action(3) (EXPERIMENTAL)

DESCRIPTION
       libpmemobj provides a transactional object store	in  persistent	memory
       (pmem) for applications that require transactions and persistent	memory
       management using	direct access storage (DAX),  which  is	 storage  that
       supports	 load/store  access without paging blocks from a block storage
       device.	Some types of non-volatile memory DIMMs	(NVDIMMs) provide this
       type  of	byte addressable access	to storage.  A persistent memory aware
       file system is typically	used to	expose the direct access  to  applica-
       tions.	Memory mapping a file from this	type of	file system results in
       load/store, non-paged access to pmem.  libpmemobj builds	on  this  type
       of  memory  mapped  file	 using	the low-level pmem support provided by
       libpmem(7), handling the	transactional  updates,	 flushing  changes  to
       persistence, and	managing recovery for the application.

       libpmemobj requires the -std=gnu99 compilation flag to build properly.

       libpmemobj is one of a collection of persistent memory libraries	avail-
       able.  The others are:

       o libpmemblk(7),	providing pmem-resident	arrays of  fixed-sized	blocks
	 with atomic updates.

       o libpmemlog(7),	providing a pmem-resident log file.

       o libpmem(7), low-level persistent memory support.

       Under  normal usage, libpmemobj will never print	messages or intention-
       ally cause the process to exit.	The only exception to this is the  de-
       bugging information, when enabled, as described under DEBUGGING AND ER-
       ROR HANDLING, below.

LIBRARY	API VERSIONING
       This section describes how the library API is versioned,	 allowing  ap-
       plications to work with an evolving API.

       The  pmemobj_check_version()  function  is used to see if the installed
       libpmemobj supports the version of the library API required by  an  ap-
       plication.  The easiest way to do this is for the application to	supply
       the compile-time	version	information, supplied by defines in <libpmemo-
       bj.h>, like this:

	      reason = pmemobj_check_version(PMEMOBJ_MAJOR_VERSION,
					     PMEMOBJ_MINOR_VERSION);
	      if (reason != NULL) {
		  /* version check failed, reason string tells you why */
	      }

       Any mismatch in the major version number	is considered a	failure, but a
       library with a newer minor version number will pass  this  check	 since
       increasing minor	versions imply backwards compatibility.

       An  application can also	check specifically for the existence of	an in-
       terface by checking for the version where  that	interface  was	intro-
       duced.	These versions are documented in this man page as follows: un-
       less otherwise specified, all interfaces	described here	are  available
       in version 1.0 of the library.  Interfaces added	after version 1.0 will
       contain the text	introduced in version x.y in the section of this manu-
       al describing the feature.

       On  success,  pmemobj_check_version() returns NULL.  Otherwise, the re-
       turn value is a static string describing	the reason the	version	 check
       failed.	 The  string  returned	by pmemobj_check_version() must	not be
       modified	or freed.

MANAGING LIBRARY BEHAVIOR
       The pmemobj_set_funcs() function	allows an application to override mem-
       ory  allocation	calls  used internally by libpmemobj.  Passing in NULL
       for any of the handlers will cause the libpmemobj default  function  to
       be  used.   The	library	 does  not make	heavy use of the system	malloc
       functions, but it does allocate approximately 4-8  kilobytes  for  each
       memory pool in use.

       By  default, libpmemobj supports	up to 1024 parallel transactions/allo-
       cations.	 For debugging purposes	it is possible to decrease this	 value
       by  setting the PMEMOBJ_NLANES environment variable to the desired lim-
       it.

DEBUGGING AND ERROR HANDLING
       If an error is detected during the call to a libpmemobj	function,  the
       application may retrieve	an error message describing the	reason for the
       failure from pmemobj_errormsg().	 This function returns a pointer to  a
       static  buffer containing the last error	message	logged for the current
       thread.	If errno was set, the error message may	include	a  description
       of  the corresponding error code	as returned by strerror(3).  The error
       message buffer is thread-local; errors encountered in one thread	do not
       affect  its value in other threads.  The	buffer is never	cleared	by any
       library function; its content is	significant only when the return value
       of the immediately preceding call to a libpmemobj function indicated an
       error, or if errno was set.  The	application must not  modify  or  free
       the error message string, but it	may be modified	by subsequent calls to
       other library functions.

       Two versions of libpmemobj are typically	 available  on	a  development
       system.	 The  normal  version, accessed	when a program is linked using
       the -lpmemobj option, is	optimized for performance.  That version skips
       checks  that impact performance and never logs any trace	information or
       performs	any run-time assertions.

       A second	version	of libpmemobj, accessed	when a program	uses  the  li-
       braries	under  /usr/lib/pmdk_debug,  contains  run-time	assertions and
       trace points.  The typical way to access	the debug version  is  to  set
       the  environment	 variable  LD_LIBRARY_PATH  to	/usr/lib/pmdk_debug or
       /usr/lib64/pmdk_debug, as appropriate.  Debugging output	is  controlled
       using the following environment variables.  These variables have	no ef-
       fect on the non-debug version of	the library.

       o PMEMOBJ_LOG_LEVEL

       The value of PMEMOBJ_LOG_LEVEL enables trace points in the  debug  ver-
       sion of the library, as follows:

       o 0  - This is the default level	when PMEMOBJ_LOG_LEVEL is not set.  No
	 log messages are emitted at this level.

       o 1 - Additional	details	on any errors detected are logged, in addition
	 to  returning	the errno-based	errors as usual.  The same information
	 may be	retrieved using	pmemobj_errormsg().

       o 2 - A trace of	basic operations is logged.

       o 3 - Enables a very verbose amount of function call tracing in the li-
	 brary.

       o 4 - Enables voluminous	and fairly obscure tracing information that is
	 likely	only useful to the libpmemobj developers.

       Unless PMEMOBJ_LOG_FILE is set, debugging output	is written to stderr.

       o PMEMOBJ_LOG_FILE

       Specifies the name of a file where all logging  information  should  be
       written.	 If the	last character in the name is "-", the PID of the cur-
       rent process will be appended to	the file name when  the	 log  file  is
       created.	  If PMEMOBJ_LOG_FILE is not set, logging output is written to
       stderr.

       See also	libpmem(7) to get information about  other  environment	 vari-
       ables affecting libpmemobj behavior.

EXAMPLE
       See  <http://pmem.io/pmdk/libpmemobj> for examples using	the libpmemobj
       API.

ACKNOWLEDGEMENTS
       libpmemobj builds on the	persistent memory programming model recommend-
       ed    by	   the	  SNIA	 NVM   Programming   Technical	 Work	Group:
       <http://snia.org/nvmp>

SEE ALSO
       OID_IS_NULL(3),	  pmemobj_alloc(3),    pmemobj_ctl_exec(3),	pmemo-
       bj_ctl_get(3),  pmemobj_ctl_set(3),  pmemobj_first(3), pmemobj_list_in-
       sert(3),	  pmemobj_memcpy_persist(3),   pmemobj_mutex_zero(3),	pmemo-
       bj_open(3),  pmemobj_root(3),  pmemobj_tx_add_range(3),	pmemobj_tx_al-
       loc(3), pmemobj_tx_begin(3),  POBJ_LAYOUT_BEGIN(3),  POBJ_LIST_HEAD(3),
       strerror(3), TOID_DECLARE(3), libpmem(7), libpmemblk(7),	libpmemlog(7),
       libvmem(7) and <http://pmem.io>

PMDK - pmemobj API version 2.3	  2019-07-10			 LIBPMEMOBJ(7)

NAME | SYNOPSIS | DESCRIPTION | LIBRARY API VERSIONING | MANAGING LIBRARY BEHAVIOR | DEBUGGING AND ERROR HANDLING | EXAMPLE | ACKNOWLEDGEMENTS | SEE ALSO

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

home | help