.\" Automatically generated by Pandoc 2.2.1 .\" .TH "PMEMOBJ_ACTION" "3" "2019-02-19" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" .hy .\" Copyright 2014-2019, Intel Corporation .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" * Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" * Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" * Neither the name of the copyright holder nor the names of its .\" contributors may be used to endorse or promote products derived .\" from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .SH NAME .PP \f[B]pmemobj_reserve\f[](), \f[B]pmemobj_xreserve\f[](), \f[B]pmemobj_defer_free\f[](), \f[B]pmemobj_set_value\f[](), \f[B]pmemobj_publish\f[](), \f[B]pmemobj_tx_publish\f[](), \f[B]pmemobj_cancel\f[](), \f[B]POBJ_RESERVE_NEW\f[](), \f[B]POBJ_RESERVE_ALLOC\f[](), \f[B]POBJ_XRESERVE_NEW\f[](),\f[B]POBJ_XRESERVE_ALLOC\f[]() \- Delayed atomicity actions (EXPERIMENTAL) .SH SYNOPSIS .IP .nf \f[C] #include\ PMEMoid\ pmemobj_reserve(PMEMobjpool\ *pop,\ struct\ pobj_action\ *act, \ \ \ \ size_t\ size,\ uint64_t\ type_num);\ (EXPERIMENTAL) PMEMoid\ pmemobj_xreserve(PMEMobjpool\ *pop,\ struct\ pobj_action\ *act, \ \ \ \ size_t\ size,\ uint64_t\ type_num,\ uint64_t\ flags);\ (EXPERIMENTAL) void\ pmemobj_defer_free(PMEMobjpool\ *pop,\ PMEMoid\ oid,\ struct\ pobj_action\ *act); void\ pmemobj_set_value(PMEMobjpool\ *pop,\ struct\ pobj_action\ *act, \ \ \ \ uint64_t\ *ptr,\ uint64_t\ value);\ (EXPERIMENTAL) int\ pmemobj_publish(PMEMobjpool\ *pop,\ struct\ pobj_action\ *actv, \ \ \ \ size_t\ actvcnt);\ (EXPERIMENTAL) int\ pmemobj_tx_publish(struct\ pobj_action\ *actv,\ size_t\ actvcnt);\ (EXPERIMENTAL) void\ pmemobj_cancel(PMEMobjpool\ *pop,\ struct\ pobj_action\ *actv, \ \ \ \ size_t\ actvcnt);\ (EXPERIMENTAL) POBJ_RESERVE_NEW(pop,\ t,\ act)\ (EXPERIMENTAL) POBJ_RESERVE_ALLOC(pop,\ t,\ size,\ act)\ (EXPERIMENTAL) POBJ_XRESERVE_NEW(pop,\ t,\ act,\ flags)\ (EXPERIMENTAL) POBJ_XRESERVE_ALLOC(pop,\ t,\ size,\ act,\ flags)\ (EXPERIMENTAL) \f[] .fi .SH DESCRIPTION .PP All of the functions described so far have an immediate effect on the persistent state of the pool, and as such, the cost of maintaining fail\-safety is paid outright and, most importantly, in the calling thread. This behavior makes implementing algorithms involving relaxed consistency guarantees difficult, if not outright impossible. .PP The following set of functions introduce a mechanism that allows one to delay the persistent publication of a set of prepared actions to an arbitrary moment in time of the execution of a program. .PP The publication is fail\-safe atomic in the scope of the entire collection of actions. If a program exits without publishing the actions, or the actions are canceled, any resources reserved by those actions are released and placed back in the pool. .PP A single action is represented by a single \f[C]struct\ pobj_action\f[]. Functions that create actions take that structure by pointer, whereas functions that publish actions take array of actions and the size of the array. The actions can be created, and published, from different threads. When creating actions, the \f[I]act\f[] argument must be non\-NULL and point to a \f[C]struct\ pobj_action\f[], the structure will be populated by the function and must not be modified or deallocated until after publishing. .PP The \f[B]pmemobj_reserve\f[]() functions performs a transient reservation of an object. Behaves similarly to \f[B]pmemobj_alloc\f[](3), but performs no modification to the persistent state. The object returned by this function can be freely modified without worrying about fail\-safe atomicity until the object has been published. Any modifications of the object must be manually persisted, just like in the case of the atomic API. .PP \f[B]pmemobj_xreserve\f[]() is equivalent to \f[B]pmemobj_reserve\f[](), but with an additional \f[I]flags\f[] argument that is a bitmask of the following values: .IP \[bu] 2 \f[B]POBJ_XALLOC_ZERO\f[] \- zero the object (and persist it) .IP \[bu] 2 \f[B]POBJ_CLASS_ID(class_id)\f[] \- allocate the object from allocation class \f[I]class_id\f[]. The class id cannot be 0. .PP \f[B]pmemobj_defer_free\f[]() function creates a deferred free action, meaning that the provided object will be freed when the action is published. Calling this function with a NULL OID is invalid and causes undefined behavior. .PP The \f[B]pmemobj_set_value\f[] function prepares an action that, once published, will modify the memory location pointed to by \f[I]ptr\f[] to \f[I]value\f[]. .PP The \f[B]pmemobj_publish\f[] function publishes the provided set of actions. The publication is fail\-safe atomic. Once done, the persistent state will reflect the changes contained in the actions. .PP The \f[B]pmemobj_tx_publish\f[] function moves the provided actions to the scope of the transaction in which it is called. Only object reservations are supported in transactional publish. Once done, the reserved objects will follow normal transactional semantics. Can only be called during \f[I]TX_STAGE_WORK\f[]. .PP The \f[B]pmemobj_cancel\f[] function releases any resources held by the provided set of actions and invalidates all actions. .PP The \f[B]POBJ_RESERVE_NEW\f[] macro is a typed variant of \f[B]pmemobj_reserve\f[]. The size of the reservation is determined from the provided type \f[I]t\f[]. .PP The \f[B]POBJ_RESERVE_ALLOC\f[] macro is a typed variant of \f[B]pmemobj_reserve\f[]. The \f[I]size\f[] of the reservation is user\-provided. .PP The \f[B]POBJ_XRESERVE_NEW\f[] and the \f[B]POBJ_XRESERVE_ALLOC\f[] macros are equivalent to \f[B]POBJ_RESERVE_NEW\f[] and the \f[B]POBJ_RESERVE_ALLOC\f[], but with an additional \f[I]flags\f[] argument defined for \f[B]pmemobj_xreserve\f[](). .SH EXAMPLES .PP The following code shows atomic append of two objects into a singly linked list. .IP .nf \f[C] struct\ list_node\ { \ \ \ \ int\ value; \ \ \ \ PMEMoid\ next; }; /*\ statically\ allocate\ the\ array\ of\ actions\ */ struct\ pobj_action\ actv[4]; /*\ reserve,\ populate\ and\ persist\ the\ first\ object\ */ PMEMoid\ tail\ =\ pmemobj_reserve(pop,\ &actv[0],\ sizeof(struct\ list_node),\ 0); if\ (TOID_IS_NULL(tail)) \ \ \ \ return\ \-1; D_RW(tail)\->value\ =\ 1; D_RW(tail)\->next\ =\ OID_NULL; pmemobj_persist(pop,\ D_RW(tail),\ sizeof(struct\ list_node)); /*\ reserve,\ populate\ and\ persist\ the\ second\ object\ */ PMEMoid\ head\ =\ pmemobj_reserve(pop,\ &actv[1],\ sizeof(struct\ list_node),\ 0); if\ (TOID_IS_NULL(head)) \ \ \ \ return\ \-1; D_RW(head)\->value\ =\ 2; D_RW(head)\->next\ =\ tail; pmemobj_persist(pop,\ D_RW(head),\ sizeof(struct\ list_node)); /*\ create\ actions\ to\ set\ the\ PMEMoid\ to\ the\ new\ values\ */ pmemobj_set_value(pop,\ &actv[2],\ &D_RO(root)\->head.pool_uuid_lo,\ head.pool_uuid_lo); pmemobj_set_value(pop,\ &actv[3],\ &D_RO(root)\->head.off,\ head.off); /*\ atomically\ publish\ the\ above\ actions\ */ pmemobj_publish(pop,\ actv,\ 4); \f[] .fi .SH RETURN VALUE .PP On success, \f[B]pmemobj_reserve\f[]() functions return a handle to the newly reserved object, otherwise an \f[I]OID_NULL\f[] is returned. .PP On success, \f[B]pmemobj_tx_publish\f[]() returns 0, otherwise, stage changes to \f[I]TX_STAGE_ONABORT\f[] and \f[I]errno\f[] is set appropriately .PP On success, \f[B]pmemobj_publish\f[]() returns 0, otherwise, returns \-1 and \f[I]errno\f[] is set appropriately. .SH SEE ALSO .PP \f[B]pmemobj_alloc\f[](3), \f[B]pmemobj_tx_alloc\f[](3), \f[B]libpmemobj\f[](7) and \f[B]\f[]