1PMEMOBJ_TX_ALLOC(3)        PMDK Programmer's Manual        PMEMOBJ_TX_ALLOC(3)
2
3
4

NAME

6       pmemobj_tx_alloc(),  pmemobj_tx_zalloc(),  pmemobj_tx_xalloc(),  pmemo‐
7       bj_tx_realloc(),  pmemobj_tx_zrealloc(),  pmemobj_tx_strdup(),   pmemo‐
8       bj_tx_wcsdup(), pmemobj_tx_free(),
9
10       TX_NEW(),  TX_ALLOC(),  TX_ZNEW(),  TX_ZALLOC(),  TX_XALLOC(), TX_REAL‐
11       LOC(), TX_ZREALLOC(), TX_STRDUP(), TX_WCSDUP(), TX_FREE()  --  transac‐
12       tional object manipulation
13

SYNOPSIS

15              #include <libpmemobj.h>
16
17              PMEMoid pmemobj_tx_alloc(size_t size, uint64_t type_num);
18              PMEMoid pmemobj_tx_zalloc(size_t size, uint64_t type_num);
19              PMEMoid pmemobj_tx_xalloc(size_t size, uint64_t type_num, uint64_t flags);
20              PMEMoid pmemobj_tx_realloc(PMEMoid oid, size_t size, uint64_t type_num);
21              PMEMoid pmemobj_tx_zrealloc(PMEMoid oid, size_t size, uint64_t type_num);
22              PMEMoid pmemobj_tx_strdup(const char *s, uint64_t type_num);
23              PMEMoid pmemobj_tx_wcsdup(const wchar_t *s, uint64_t type_num);
24              int pmemobj_tx_free(PMEMoid oid);
25
26              TX_NEW(TYPE)
27              TX_ALLOC(TYPE, size_t size)
28              TX_ZNEW(TYPE)
29              TX_ZALLOC(TYPE, size_t size)
30              TX_XALLOC(TYPE, size_t size, uint64_t flags)
31              TX_REALLOC(TOID o, size_t size)
32              TX_ZREALLOC(TOID o, size_t size)
33              TX_STRDUP(const char *s, uint64_t type_num)
34              TX_WCSDUP(const wchar_t *s, uint64_t type_num)
35              TX_FREE(TOID o)
36

DESCRIPTION

38       The  pmemobj_tx_alloc() function transactionally allocates a new object
39       of given size and type_num.  In contrast to the non-transactional allo‐
40       cations,  the  objects  are  added to the internal object containers of
41       given type_num only after the transaction is committed, making the  ob‐
42       jects  visible  to  the POBJ_FOREACH_*() macros.  This function must be
43       called during TX_STAGE_WORK.
44
45       The pmemobj_tx_zalloc() function transactionally allocates a new zeroed
46       object of given size and type_num.  This function must be called during
47       TX_STAGE_WORK.
48
49       The pmemobj_tx_xalloc() function transactionally allocates a new object
50       of  given  size  and  type_num.  The flags argument is a bitmask of the
51       following values:
52
53       · POBJ_XALLOC_ZERO - zero the object (equivalent of pmemobj_tx_zalloc)
54
55       · POBJ_XALLOC_NO_FLUSH - skip flush on commit (when  application  deals
56         with flushing or uses pmemobj_memcpy_persist)
57
58       · POBJ_CLASS_ID(class_id)  -  allocate  the  object from the allocation
59         class with id equal to class_id
60
61       This function must be called during TX_STAGE_WORK.
62
63       The pmemobj_tx_realloc() function transactionally resizes  an  existing
64       object  to  the given size and changes its type to type_num.  If oid is
65       OID_NULL, then the call is equivalent  to  pmemobj_tx_alloc(pop,  size,
66       type_num).   If size is equal to zero and oid is not OID_NULL, then the
67       call is equivalent to pmemobj_tx_free(oid).  If the new size is  larger
68       than  the  old  size,  the  added memory will not be initialized.  This
69       function must be called during TX_STAGE_WORK.
70
71       The pmemobj_tx_zrealloc() function transactionally resizes an  existing
72       object  to the given size and changes its type to type_num.  If the new
73       size is larger than the old size, the extended  new  space  is  zeroed.
74       This function must be called during TX_STAGE_WORK.
75
76       The pmemobj_tx_strdup() function transactionally allocates a new object
77       containing a duplicate of the string s and assigns it a type  type_num.
78       This function must be called during TX_STAGE_WORK.
79
80       The pmemobj_tx_wcsdup() function transactionally allocates a new object
81       containing a duplicate of the wide character string s and assigns it  a
82       type type_num.  This function must be called during TX_STAGE_WORK.
83
84       The pmemobj_tx_free() function transactionally frees an existing object
85       referenced by oid.  This function must be called during TX_STAGE_WORK.
86
87       The TX_NEW() macro transactionally allocates a new object of given TYPE
88       and  assigns  it a type number read from the typed OID.  The allocation
89       size is determined from the size of the  user-defined  structure  TYPE.
90       If  successful  and  called during TX_STAGE_WORK it returns a handle to
91       the newly  allocated  object.   Otherwise,  the  stage  is  changed  to
92       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
93
94       The  TX_ALLOC()  macro  transactionally allocates a new object of given
95       TYPE and assigns it a type number read from the typed OID.  The alloca‐
96       tion size is passed by size parameter.  If successful and called during
97       TX_STAGE_WORK it returns a handle to the newly allocated object.   Oth‐
98       erwise, the stage is set to TX_STAGE_ONABORT, OID_NULL is returned, and
99       errno is set appropriately.
100
101       The TX_ZNEW() macro transactionally allocates a new  zeroed  object  of
102       given  TYPE  and assigns it a type number read from the typed OID.  The
103       allocation size is determined from the size of the user-defined  struc‐
104       ture  TYPE.  If successful and called during TX_STAGE_WORK it returns a
105       handle to the newly allocated  object.   Otherwise,  stage  changes  to
106       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
107
108       The  TX_ZALLOC() macro transactionally allocates a new zeroed object of
109       given TYPE and assigns it a type number read from the typed  OID.   The
110       allocation  size  is passed by size argument.  If successful and called
111       during TX_STAGE_WORK it returns a handle to the newly allocated object.
112       Otherwise,  the  stage  is changed to TX_STAGE_ONABORT, OID_NULL is re‐
113       turned, and errno is set appropriately.
114
115       The TX_XALLOC() macro transactionally allocates a new object  of  given
116       TYPE and assigns it a type number read from the typed OID.  The alloca‐
117       tion size is passed by size argument.  The flags argument is a  bitmask
118       of  values  described  in pmemobj_tx_xalloc section.  If successful and
119       called during TX_STAGE_WORK it returns a handle to the newly  allocated
120       object.   Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL
121       is returned, and errno is set appropriately.
122
123       The TX_REALLOC() macro transactionally resizes an existing object  ref‐
124       erenced by a handle o to the given size.  If successful and called dur‐
125       ing TX_STAGE_WORK it returns a handle to the reallocated object.   Oth‐
126       erwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned,
127       and errno is set appropriately.
128
129       The TX_ZREALLOC() macro transactionally resizes an existing object ref‐
130       erenced  by  a  handle  o to the given size.  If the new size is larger
131       than the old size, the extended new space is zeroed.  If successful and
132       called  during TX_STAGE_WORK it returns a handle to the reallocated ob‐
133       ject.  Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is
134       returned, and errno is set appropriately.
135
136       The TX_STRDUP() macro transactionally allocates a new object containing
137       a duplicate of the string s and assigns it type type_num.  If  success‐
138       ful  and  called  during TX_STAGE_WORK it returns a handle to the newly
139       allocated object.  Otherwise, the stage is changed to TX_STAGE_ONABORT,
140       OID_NULL is returned, and errno is set appropriately.
141
142       The TX_WCSDUP() macro transactionally allocates a new object containing
143       a duplicate of the wide character  string  s  and  assigns  it  a  type
144       type_num.   If successful and called during TX_STAGE_WORK, it returns a
145       handle to the newly allocated object.  Otherwise, the stage is  changed
146       to  TX_STAGE_ONABORT,  OID_NULL is returned, and errno is set appropri‐
147       ately.
148
149       The TX_FREE() macro transactionally frees the memory space  represented
150       by  an  object  handle o.  If o is OID_NULL, no operation is performed.
151       If successful and called during  TX_STAGE_WORK,  TX_FREE()  returns  0.
152       Otherwise, the stage is changed to TX_STAGE_ONABORT and an error number
153       is returned.
154

RETURN VALUE

156       On  success,  the   pmemobj_tx_alloc()   ,pmemobj_tx_zalloc(),   pmemo‐
157       bj_tx_xalloc(),  pmemobj_tx_strdup()  and pmemobj_tx_wcsdup() functions
158       return a handle to the newly allocated object.  Otherwise, the stage is
159       changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set ap‐
160       propriately.  If size equals 0, OID_NULL is returned and errno  is  set
161       appropriately.
162
163       On  success,  pmemobj_tx_realloc()  and  pmemobj_tx_zrealloc() return a
164       handle to the resized object.   Otherwise,  the  stage  is  changed  to
165       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
166       Note that the object handle value may change as a result  of  realloca‐
167       tion.
168
169       On  success,  pmemobj_tx_free() returns 0.  Otherwise, the stage is set
170       to TX_STAGE_ONABORT and an error number is returned.
171

SEE ALSO

173       pmemobj_tx_add_range(3),  **pmemobj_tx_begin*(3),   libpmemobj(7)   and
174       <http://pmem.io>
175
176
177
178PMDK - pmemobj API version 2.3    2018-03-13               PMEMOBJ_TX_ALLOC(3)
Impressum