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 allocated object  (equivalent  of  pmemo‐
54         bj_tx_zalloc)
55
56       · POBJ_XALLOC_NO_FLUSH  -  skip flush on commit (when application deals
57         with flushing or uses pmemobj_memcpy_persist)
58
59       · POBJ_CLASS_ID(class_id) - allocate  an  object  from  the  allocation
60         class with id equal to class_id
61
62       · POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified
63         by arena_id.  The arena must exist, otherwise, the behavior is  unde‐
64         fined.   If  arena_id  is equal 0, then arena assigned to the current
65         thread will be used.
66
67       This function must be called during TX_STAGE_WORK.
68
69       The pmemobj_tx_realloc() function transactionally resizes  an  existing
70       object  to  the given size and changes its type to type_num.  If oid is
71       OID_NULL, then the call is equivalent  to  pmemobj_tx_alloc(pop,  size,
72       type_num).   If size is equal to zero and oid is not OID_NULL, then the
73       call is equivalent to pmemobj_tx_free(oid).  If the new size is  larger
74       than  the  old  size,  the  added memory will not be initialized.  This
75       function must be called during TX_STAGE_WORK.
76
77       The pmemobj_tx_zrealloc() function transactionally resizes an  existing
78       object  to the given size and changes its type to type_num.  If the new
79       size is larger than the old size, the extended  new  space  is  zeroed.
80       This function must be called during TX_STAGE_WORK.
81
82       The pmemobj_tx_strdup() function transactionally allocates a new object
83       containing a duplicate of the string s and assigns it a type  type_num.
84       This function must be called during TX_STAGE_WORK.
85
86       The pmemobj_tx_wcsdup() function transactionally allocates a new object
87       containing a duplicate of the wide character string s and assigns it  a
88       type type_num.  This function must be called during TX_STAGE_WORK.
89
90       The pmemobj_tx_free() function transactionally frees an existing object
91       referenced by oid.  This function must be called during TX_STAGE_WORK.
92
93       The TX_NEW() macro transactionally allocates a new object of given TYPE
94       and  assigns  it a type number read from the typed OID.  The allocation
95       size is determined from the size of the  user-defined  structure  TYPE.
96       If  successful  and  called during TX_STAGE_WORK it returns a handle to
97       the newly  allocated  object.   Otherwise,  the  stage  is  changed  to
98       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
99
100       The  TX_ALLOC()  macro  transactionally allocates a new object of given
101       TYPE and assigns it a type number read from the typed OID.  The alloca‐
102       tion size is passed by size parameter.  If successful and called during
103       TX_STAGE_WORK it returns a handle to the newly allocated object.   Oth‐
104       erwise, the stage is set to TX_STAGE_ONABORT, OID_NULL is returned, and
105       errno is set appropriately.
106
107       The TX_ZNEW() macro transactionally allocates a new  zeroed  object  of
108       given  TYPE  and assigns it a type number read from the typed OID.  The
109       allocation size is determined from the size of the user-defined  struc‐
110       ture  TYPE.  If successful and called during TX_STAGE_WORK it returns a
111       handle to the newly allocated  object.   Otherwise,  stage  changes  to
112       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
113
114       The  TX_ZALLOC() macro transactionally allocates a new zeroed object of
115       given TYPE and assigns it a type number read from the typed  OID.   The
116       allocation  size  is passed by size argument.  If successful and called
117       during TX_STAGE_WORK it returns a handle to the newly allocated object.
118       Otherwise,  the  stage  is changed to TX_STAGE_ONABORT, OID_NULL is re‐
119       turned, and errno is set appropriately.
120
121       The TX_XALLOC() macro transactionally allocates a new object  of  given
122       TYPE and assigns it a type number read from the typed OID.  The alloca‐
123       tion size is passed by size argument.  The flags argument is a  bitmask
124       of  values  described  in pmemobj_tx_xalloc section.  If successful and
125       called during TX_STAGE_WORK it returns a handle to the newly  allocated
126       object.   Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL
127       is returned, and errno is set appropriately.
128
129       The TX_REALLOC() macro transactionally resizes an existing object  ref‐
130       erenced by a handle o to the given size.  If successful and called dur‐
131       ing TX_STAGE_WORK it returns a handle to the reallocated object.   Oth‐
132       erwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned,
133       and errno is set appropriately.
134
135       The TX_ZREALLOC() macro transactionally resizes an existing object ref‐
136       erenced  by  a  handle  o to the given size.  If the new size is larger
137       than the old size, the extended new space is zeroed.  If successful and
138       called  during TX_STAGE_WORK it returns a handle to the reallocated ob‐
139       ject.  Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is
140       returned, and errno is set appropriately.
141
142       The TX_STRDUP() macro transactionally allocates a new object containing
143       a duplicate of the string s and assigns it type type_num.  If  success‐
144       ful  and  called  during TX_STAGE_WORK it returns a handle to the newly
145       allocated object.  Otherwise, the stage is changed to TX_STAGE_ONABORT,
146       OID_NULL is returned, and errno is set appropriately.
147
148       The TX_WCSDUP() macro transactionally allocates a new object containing
149       a duplicate of the wide character  string  s  and  assigns  it  a  type
150       type_num.   If successful and called during TX_STAGE_WORK, it returns a
151       handle to the newly allocated object.  Otherwise, the stage is  changed
152       to  TX_STAGE_ONABORT,  OID_NULL is returned, and errno is set appropri‐
153       ately.
154
155       The TX_FREE() macro transactionally frees the memory space  represented
156       by  an  object  handle o.  If o is OID_NULL, no operation is performed.
157       If successful and called during  TX_STAGE_WORK,  TX_FREE()  returns  0.
158       Otherwise, the stage is changed to TX_STAGE_ONABORT and an error number
159       is returned.
160

RETURN VALUE

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

SEE ALSO

179       pmemobj_tx_add_range(3),  **pmemobj_tx_begin*(3),   libpmemobj(7)   and
180       <http://pmem.io>
181
182
183
184PMDK - pmemobj API version 2.3    2019-07-10               PMEMOBJ_TX_ALLOC(3)
Impressum