.\" Automatically generated by Pandoc 2.9.2.1 .\" .TH "" "" "2023-05-31" "PMDK - " "PMDK Programmer's Manual" .hy .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright 2017-2020, Intel Corporation .SH NAME .PP \f[B]pmemobj_alloc\f[R](), \f[B]pmemobj_xalloc\f[R](), \f[B]pmemobj_zalloc\f[R](), \f[B]pmemobj_realloc\f[R](), \f[B]pmemobj_zrealloc\f[R](), \f[B]pmemobj_strdup\f[R](), \f[B]pmemobj_wcsdup\f[R](), \f[B]pmemobj_alloc_usable_size\f[R](), \f[B]pmemobj_defrag\f[R](), \f[B]POBJ_NEW\f[R](), \f[B]POBJ_ALLOC\f[R](), \f[B]POBJ_ZNEW\f[R](), \f[B]POBJ_ZALLOC\f[R](), \f[B]POBJ_REALLOC\f[R](), \f[B]POBJ_ZREALLOC\f[R](), \f[B]POBJ_FREE\f[R]() - non-transactional atomic allocations .SH SYNOPSIS .IP .nf \f[C] #include 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) \f[R] .fi .SH DESCRIPTION .PP 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. .PP 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. .PP The allocations are always aligned to a cache-line boundary. .PP The \f[I]pmemobj_constr\f[R] type represents a constructor for atomic allocation from the persistent memory heap associated with memory pool \f[I]pop\f[R]. \f[I]ptr\f[R] is a pointer to the allocated memory area and \f[I]arg\f[R] is a user-defined argument passed to the constructor. .PP The \f[B]pmemobj_alloc\f[R]() function allocates a new object from the persistent memory heap associated with memory pool \f[I]pop\f[R]. The \f[I]PMEMoid\f[R] of the allocated object is stored in \f[I]oidp\f[R]. If \f[I]oidp\f[R] is NULL, then the newly allocated object may be accessed only by iterating objects in the object container associated with the type number \f[I]type_num\f[R], as described in \f[B]POBJ_FOREACH\f[R](3). If \f[I]oidp\f[R] points to a memory location from the \f[B]pmemobj\f[R] heap, \f[I]oidp\f[R] is modified atomically. Before returning, \f[B]pmemobj_alloc\f[R]() calls the \f[I]constructor\f[R] function, passing the pool handle \f[I]pop\f[R], the pointer to the newly allocated object in \f[I]ptr\f[R], and the \f[I]arg\f[R] 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. \f[I]size\f[R] 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 \f[I]type_num\f[R]. .PP \f[B]pmemobj_xalloc\f[R]() is equivalent to \f[B]pmemobj_alloc\f[R](), but with an additional \f[I]flags\f[R] argument that is a bitmask of the following values: .IP \[bu] 2 \f[B]POBJ_XALLOC_ZERO\f[R] - zero the allocated object (equivalent of \f[B]pmemobj_zalloc\f[R]()) .IP \[bu] 2 \f[B]POBJ_CLASS_ID(class_id)\f[R] - allocate an object from the allocation class \f[I]class_id\f[R]. The class id cannot be 0. .IP \[bu] 2 \f[B]POBJ_ARENA_ID(arena_id)\f[R] - allocate an object from the arena specified by \f[I]arena_id\f[R]. The arena must exist, otherwise, the behavior is undefined. If \f[I]arena_id\f[R] is equal 0, then arena assigned to the current thread will be used. .PP The \f[B]pmemobj_zalloc\f[R]() function allocates a new zeroed object from the persistent memory heap associated with memory pool \f[I]pop\f[R]. The \f[I]PMEMoid\f[R] of the allocated object is stored in \f[I]oidp\f[R]. If \f[I]oidp\f[R] is NULL, then the newly allocated object may be accessed only by iterating objects in the object container associated with the type number \f[I]type_num\f[R], as described in \f[B]POBJ_FOREACH\f[R](3). If \f[I]oidp\f[R] points to a memory location from the \f[B]pmemobj\f[R] heap, \f[I]oidp\f[R] is modified atomically. \f[I]size\f[R] 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 \f[I]type_num\f[R]. .PP The \f[B]pmemobj_free\f[R]() function frees the memory space represented by \f[I]oidp\f[R], which must have been allocated by a previous call to \f[B]pmemobj_alloc\f[R](), \f[B]pmemobj_xalloc\f[R](), \f[B]pmemobj_zalloc\f[R](), \f[B]pmemobj_realloc\f[R](), or \f[B]pmemobj_zrealloc\f[R](). \f[B]pmemobj_free\f[R]() provides the same semantics as \f[B]free\f[R](3), but instead of operating on the process heap supplied by the system, it operates on the persistent memory heap. If \f[I]oidp\f[R] is \f[B]OID_NULL\f[R], no operation is performed. If \f[I]oidp\f[R] is NULL or if it points to the root object\[cq]s \f[I]OID\f[R], the behavior of \f[B]pmemobj_free\f[R]() is undefined. \f[I]oidp\f[R] is set to \f[B]OID_NULL\f[R] after the memory is freed. If \f[I]oidp\f[R] points to a memory location from the \f[B]pmemobj\f[R] heap, \f[I]oidp\f[R] is modified atomically. .PP The \f[B]pmemobj_realloc\f[R]() function changes the size of the object represented by \f[I]oidp\f[R] to \f[I]size\f[R] bytes. \f[B]pmemobj_realloc\f[R]() provides similar semantics to \f[B]realloc\f[R](3), but operates on the persistent memory heap associated with memory pool \f[I]pop\f[R]. The resized object is also added or moved to the internal container associated with type number \f[I]type_num\f[R]. 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 \f[I]not\f[R] be initialized. If \f[I]oidp\f[R] is \f[I]OID_NULL\f[R], then the call is equivalent to \f[I]pmemobj_alloc(pop, size, type_num)\f[R]. If \f[I]size\f[R] is equal to zero, and \f[I]oidp\f[R] is not \f[B]OID_NULL\f[R], then the call is equivalent to \f[I]pmemobj_free(oid)\f[R]. Unless \f[I]oidp\f[R] is \f[B]OID_NULL\f[R], it must have been allocated by an earlier call to \f[B]pmemobj_alloc\f[R](), \f[B]pmemobj_xalloc\f[R](), \f[B]pmemobj_zalloc\f[R](), \f[B]pmemobj_realloc\f[R](), or \f[B]pmemobj_zrealloc\f[R](). Note that the object handle value may change as a result of reallocation. If the object was moved, the memory space represented by \f[I]oid\f[R] is reclaimed. If \f[I]oidp\f[R] points to a memory location from the \f[B]pmemobj\f[R] heap, \f[I]oidp\f[R] is modified atomically. If \f[I]oidp\f[R] is NULL or if it points to the root object\[cq]s \f[I]OID\f[R], the behavior of \f[B]pmemobj_realloc\f[R]() is undefined. .PP \f[B]pmemobj_zrealloc\f[R]() is equivalent to \f[B]pmemobj_realloc\f[R](), except that if the new size is larger than the old size, the added memory will be zeroed. .PP The \f[B]pmemobj_strdup\f[R]() function stores a handle to a new object in \f[I]oidp\f[R] which is a duplicate of the string \f[I]s\f[R]. \f[B]pmemobj_strdup\f[R]() provides the same semantics as \f[B]strdup\f[R](3), but operates on the persistent memory heap associated with memory pool \f[I]pop\f[R]. If \f[I]oidp\f[R] is NULL, then the newly allocated object may be accessed only by iterating objects in the object container associated with type number \f[I]type_num\f[R], as described in \f[B]POBJ_FOREACH\f[R](3). If \f[I]oidp\f[R] points to a memory location from the \f[B]pmemobj\f[R] heap, \f[I]oidp\f[R] is modified atomically. The allocated string object is also added to the internal container associated with type number \f[I]type_num\f[R]. Memory for the new string is obtained with \f[B]pmemobj_alloc\f[R](), on the given memory pool, and can be freed with \f[B]pmemobj_free\f[R]() on the same memory pool. .PP \f[B]pmemobj_wcsdup\f[R]() is equivalent to \f[B]pmemobj_strdup\f[R](), but operates on a wide character string (wchar_t) rather than a standard character string. .PP The \f[B]pmemobj_alloc_usable_size\f[R]() function provides the same semantics as \f[B]malloc_usable_size\f[R](3), but instead of the process heap supplied by the system, it operates on the persistent memory heap. .PP The \f[B]POBJ_NEW\f[R]() macro is a wrapper around the \f[B]pmemobj_alloc\f[R]() function. Instead of taking a pointer to \f[I]PMEMoid\f[R], it takes a pointer to the typed \f[I]OID\f[R] of type name \f[I]TYPE\f[R], and passes the size and type number from the typed \f[I]OID\f[R] to \f[B]pmemobj_alloc\f[R](). .PP The \f[B]POBJ_ALLOC\f[R]() macro is equivalent to \f[B]POBJ_NEW\f[R], except that instead of using the size of the typed \f[I]OID\f[R], passes \f[I]size\f[R] to \f[B]pmemobj_alloc\f[R](). .PP The \f[B]POBJ_ZNEW\f[R]() macro is a wrapper around the \f[B]pmemobj_zalloc\f[R]() function. Instead of taking a pointer to \f[I]PMEMoid\f[R], it takes a pointer to the typed \f[I]OID\f[R] of type name \f[I]TYPE\f[R], and passes the size and type number from the typed \f[I]OID\f[R] to \f[B]pmemobj_zalloc\f[R](). .PP The \f[B]POBJ_ZALLOC\f[R]() macro is equivalent to \f[B]POBJ_ZNEW\f[R], except that instead of using the size of the typed \f[I]OID\f[R], passes \f[I]size\f[R] to \f[B]pmemobj_zalloc\f[R](). .PP The \f[B]POBJ_REALLOC\f[R]() macro is a wrapper around the \f[B]pmemobj_realloc\f[R]() function. Instead of taking a pointer to \f[I]PMEMoid\f[R], it takes a pointer to the typed \f[I]OID\f[R] of type name \f[I]TYPE\f[R], and passes the type number from the typed \f[I]OID\f[R] to \f[B]pmemobj_realloc\f[R](). .PP The \f[B]POBJ_ZREALLOC\f[R]() macro is a wrapper around the \f[B]pmemobj_zrealloc\f[R]() function. Instead of taking a pointer to \f[I]PMEMoid\f[R], it takes a pointer to the typed \f[I]OID\f[R] of type name \f[I]TYPE\f[R], and passes the type number from the typed \f[I]OID\f[R] to \f[B]pmemobj_zrealloc\f[R](). .PP The \f[B]POBJ_FREE\f[R]() macro is a wrapper around the \f[B]pmemobj_free\f[R]() function which takes a pointer to the typed \f[I]OID\f[R] instead of to \f[I]PMEMoid\f[R]. .PP The \f[B]pmemobj_defrag\f[R]() function performs defragmentation on the objects provided through the array of pointers to PMEMoids \f[I]oidv\f[R] with size \f[I]oidcnt\f[R]. 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 \f[B]pmemobj_defrag\f[R] 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 \f[I]pop\f[R] or, in case of pointers, can also reside in volatile memory. Defragmentation across pools is not supported. Objects in the array that are \f[I]OID_NULL\f[R] are skipped over and no operation is performed on them. All other objects must have been allocated by an earlier call to \f[B]pmemobj_alloc\f[R](), \f[B]pmemobj_xalloc\f[R](), \f[B]pmemobj_zalloc\f[R](), \f[B]pmemobj_realloc\f[R](), \f[B]pmemobj_zrealloc\f[R](), \f[B]pmemobj_strdup\f[R]() or \f[B]pmemobj_wcsdup\f[R](). The \f[I]result\f[R] variable is an instance of \f[I]struct pobj_defrag_result\f[R] and, if not NULL, can be used to read \f[I]total\f[R], the number of objects found that were processed, and \f[I]relocated\f[R], 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 \f[B]pmemobj_defrag\f[R]() indicated a failure. This is because the failure might have occurred after some objects were already processed. .SH RETURN VALUE .PP On success, \f[B]pmemobj_alloc\f[R]() and \f[B]pmemobj_xalloc\f[R] return 0. If \f[I]oidp\f[R] is not NULL, the \f[I]PMEMoid\f[R] of the newly allocated object is stored in \f[I]oidp\f[R]. If the allocation fails, -1 is returned and \f[I]errno\f[R] is set appropriately. If the constructor returns a non-zero value, the allocation is canceled, -1 is returned, and \f[I]errno\f[R] is set to \f[B]ECANCELED\f[R]. If \f[I]size\f[R] equals 0, or the \f[I]flags\f[R] for \f[B]pmemobj_xalloc\f[R] are invalid, -1 is returned, \f[I]errno\f[R] is set to \f[B]EINVAL\f[R], and \f[I]oidp\f[R] is left untouched. .PP On success, \f[B]pmemobj_zalloc\f[R]() returns 0. If \f[I]oidp\f[R] is not NULL, the \f[I]PMEMoid\f[R] of the newly allocated object is stored in \f[I]oidp\f[R]. If the allocation fails, it returns -1 and sets \f[I]errno\f[R] appropriately. If \f[I]size\f[R] equals 0, it returns -1, sets \f[I]errno\f[R] to \f[B]EINVAL\f[R], and leaves \f[I]oidp\f[R] untouched. .PP The \f[B]pmemobj_free\f[R]() function returns no value. .PP On success, \f[B]pmemobj_realloc\f[R]() and \f[B]pmemobj_zrealloc\f[R]() return 0 and update \f[I]oidp\f[R] if necessary. On error, they return -1 and set \f[I]errno\f[R] appropriately. .PP On success, \f[B]pmemobj_strdup\f[R]() and \f[B]pmemobj_wcsdup\f[R]() return 0. If \f[I]oidp\f[R] is not NULL, the \f[I]PMEMoid\f[R] of the duplicated string object is stored in \f[I]oidp\f[R]. If \f[I]s\f[R] is NULL, they return -1, set \f[I]errno\f[R] to \f[B]EINVAL\f[R], and leave \f[I]oidp\f[R] untouched. On other errors, they return -1 and set \f[I]errno\f[R] appropriately. .PP The \f[B]pmemobj_alloc_usable_size\f[R]() function returns the number of usable bytes in the object represented by \f[I]oid\f[R]. If \f[I]oid\f[R] is \f[B]OID_NULL\f[R], it returns 0. .PP On success, \f[B]pmemobj_defrag\f[R]() 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. .SH SEE ALSO .PP \f[B]free\f[R](3), \f[B]POBJ_FOREACH\f[R](3), \f[B]realloc\f[R](3), \f[B]strdup\f[R](3), \f[B]wcsdup\f[R](3), \f[B]libpmemobj\f[R](7) and \f[B]\f[R]