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

NAME

6       pmempool_sync(),  pmempool_transform()  -  pool set synchronization and
7       transformation
8

SYNOPSIS

10              #include <libpmempool.h>
11
12              int pmempool_sync(const char *poolset_file,
13                  unsigned flags); (EXPERIMENTAL)
14              int pmempool_transform(const char *poolset_file_src,
15                  const char *poolset_file_dst, unsigned flags); (EXPERIMENTAL)
16

DESCRIPTION

18       The pmempool_sync() function synchronizes data between replicas  within
19       a pool set.
20
21       pmempool_sync() accepts two arguments:
22
23poolset_file - a path to a pool set file,
24
25flags  -  a combination of flags (ORed) which modify how synchroniza‐
26         tion is performed.
27
28         NOTE: Only the pool set file used to create the pool should  be  used
29         for syncing the pool.
30
31         NOTE:  The  pmempool_sync() cannot do anything useful if there are no
32         replicas in the pool set.  In such case, it fails with an error.
33
34         NOTE: At the moment, replication is only supported for  libpmemobj(7)
35         pools, so pmempool_sync() cannot be used with other pool types (libp‐
36         memlog(7), libpmemblk(7)).
37
38       The following flags are available:
39
40PMEMPOOL_SYNC_DRY_RUN - do not apply changes, only check for viabili‐
41         ty of synchronization.
42
43       pmempool_sync()  checks that the metadata of all replicas in a pool set
44       is consistent, i.e. all parts are healthy, and if any of them  is  not,
45       the  corrupted or missing parts are recreated and filled with data from
46       one of the healthy replicas.
47
48       If a pool set has the option SINGLEHDR (see poolset(5)),  the  internal
49       metadata  of each replica is limited to the beginning of the first part
50       in the replica.  If the option NOHDRS is used, replicas contain no  in‐
51       ternal  metadata.   In  both  cases, only the missing parts or the ones
52       which cannot be opened are recreated with the pmempool_sync() function.
53
54       pmempool_transform() modifies the internal structure of a pool set.  It
55       supports the following operations:
56
57       • adding one or more replicas,
58
59       • removing one or more replicas ,
60
61       • adding or removing pool set options.
62
63       Only one of the above operations can be performed at a time.
64
65       pmempool_transform() accepts three arguments:
66
67poolset_file_src  - pathname of the pool set file for the source pool
68         set to be changed,
69
70poolset_file_dst - pathname of the pool set file that defines the new
71         structure of the pool set,
72
73flags  -  a combination of flags (ORed) which modify how synchroniza‐
74         tion is performed.
75
76       The following flags are available:
77
78PMEMPOOL_TRANSFORM_DRY_RUN - do not apply changes, only check for vi‐
79         ability of transformation.
80
81       When adding or deleting replicas, the two pool set files can differ on‐
82       ly in the definitions of replicas which are to  be  added  or  deleted.
83       When  adding or removing pool set options (see poolset(5)), the rest of
84       both pool set files have to be of the same structure.  The operation of
85       adding/removing  a  pool set option can be performed on a pool set with
86       local replicas only.  To add/remove a pool set option  to/from  a  pool
87       set  with remote replicas, one has to remove the remote replicas first,
88       then add/remove the option, and finally recreate  the  remote  replicas
89       having  added/removed  the pool set option to/from the remote replicas'
90       poolset files.  To add a replica it is necessary for its effective size
91       to  match or exceed the pool size.  Otherwise the whole operation fails
92       and no changes are applied.  If none of the pool set options  is  used,
93       the  effective  size  of  a replica is the sum of sizes of all its part
94       files decreased by 4096 bytes per each part file.  The  4096  bytes  of
95       each  part  file  is utilized for storing internal metadata of the pool
96       part files.  If the option SINGLEHDR is used, the effective size  of  a
97       replica  is  the  sum  of sizes of all its part files decreased once by
98       4096 bytes.  In this case only the first part contains internal metada‐
99       ta.   If  the option NOHDRS is used, the effective size of a replica is
100       the sum of sizes of all its part files.  In this case none of the parts
101       contains internal metadata.
102
103              NOTE:  At  the moment, transform operation is only supported for
104              libpmemobj(7) pools, so pmempool_transform() cannot be used with
105              other pool types (libpmemlog(7), libpmemblk(7)).
106

RETURN VALUE

108       pmempool_sync()  and  pmempool_transform() return 0 on success.  Other‐
109       wise, they return -1 and set errno appropriately.
110

ERRORS

112       EINVAL Invalid format of the input/output pool set file.
113
114       EINVAL Unsupported flags value.
115
116       EINVAL There is only master replica  defined  in  the  input  pool  set
117       passed to pmempool_sync().
118
119       EINVAL  The  source  pool  set  passed to pmempool_transform() is not a
120       libpmemobj pool.
121
122       EINVAL The input and output pool sets  passed  to  pmempool_transform()
123       are identical.
124
125       EINVAL Attempt to perform more than one transform operation at a time.
126
127       ENOTSUP  The pool set contains a remote replica, but remote replication
128       is not supported (librpmem(7) is not available).
129

NOTES

131       The pmempool_sync() API is experimental and it  may  change  in  future
132       versions of the library.
133
134       The  pmempool_transform()  API is experimental and it may change in fu‐
135       ture versions of the library.
136

SEE ALSO

138       libpmemlog(7), libpmemobj(7) and <https://pmem.io>
139
140
141
142PMDK - pmempool API version 1.3   2022-08-25                  PMEMPOOL_SYNC(3)
Impressum