Line data Source code
1 : #ifndef HEADER_fd_src_util_checkpt_fd_checkpt_h
2 : #define HEADER_fd_src_util_checkpt_fd_checkpt_h
3 :
4 : /* APIs for fast parallel compressed checkpoint and restore. Concepts:
5 :
6 : - A checkpoint contains of zero or more frames.
7 :
8 : - Each frame resides in a disjoint contiguous sequence of bytes in
9 : the checkpoint and contains a sequence of zero of more data
10 : buffers.
11 :
12 : - Data buffers can have (up to physical limitation) arbitrary
13 : variable byte size.
14 :
15 : - A frame has a style that specifies how data buffers have been
16 : encoded into it.
17 :
18 : - Buffers in a RAW frame are stored verbatim with no gaps. As such,
19 : the space needed for a raw frame and the location of buffers in a
20 : raw frame can computed exactly up front.
21 :
22 : - Buffers in a LZ4 frame are stored via LZ4 streaming compression. A
23 : worst case upper bound for the space needed for a LZ4 frame can be
24 : computed up front, roughly:
25 :
26 : (256/255) total_sz_all_buffers + 19 buffer_count.
27 :
28 : The location of buffers in LZ4 frame is not practically computable
29 : in advance and decompression of a buffer in a frame depends on
30 : previous buffers in that frame.
31 :
32 : - Checkpoints can be read and written in a streaming IO mode or in a
33 : memory IO mode with the exact same APIs (i.e. no changes to the
34 : calling code outside of specifying the mode when starting a
35 : checkpoint or a restore). The checkpoint and restore processes
36 : will produce bit-level identical results regardless of mode.
37 :
38 : - Frames are independent such that different frames can be generated
39 : in parallel. Each frame generated will be bit-level identical
40 : regardless how generation is distributed over threads.
41 :
42 : - Similarly, frames can restored in parallel. The restored results
43 : will be bit-level identical regardles how restoration is
44 : distributed over threads.
45 :
46 : - As such, arbitrary streaming/mmio serial/parallel operation is fine
47 : (e.g. have a single thread write a checkpoint file with streaming
48 : I/O and then use multiple threads to restore from that checkpoint
49 : file with memory mapped I/O). */
50 :
51 : #include "../log/fd_log.h"
52 :
53 : /* FD_CHECKPT_SUCCESS / FD_CHECKPT_ERR_* are return values from various
54 : fd_checkpt APIs. SUCCESS is zero and ERR_* are negative integers. */
55 :
56 8736939 : #define FD_CHECKPT_SUCCESS (0) /* operation was successful */
57 99 : #define FD_CHECKPT_ERR_INVAL (-1) /* operation failed because bad input arguments */
58 15 : #define FD_CHECKPT_ERR_UNSUP (-2) /* operation failed because it is unsupported on this target */
59 9 : #define FD_CHECKPT_ERR_IO (-3) /* operation failed because an I/O error occurred */
60 6 : #define FD_CHECKPT_ERR_COMP (-4) /* operation failed because a compressor/decompressor error occurred */
61 :
62 : /* FD_CHECKPT_FRAME_STYLE_* specify a checkpoint frame style. These are
63 : positive integers. */
64 :
65 4361895 : #define FD_CHECKPT_FRAME_STYLE_RAW (1) /* uncompressed frame */
66 3586341 : #define FD_CHECKPT_FRAME_STYLE_LZ4 (2) /* lz4 compressed frame */
67 :
68 814788 : #define FD_CHECKPT_FRAME_STYLE_DEFAULT FD_CHECKPT_FRAME_STYLE_RAW
69 :
70 : /* FD_CHECKPT_WBUF_MIN is the minimum write buffer size needed by a
71 : fd_checkpt_t in streaming mode. Must be at least 65813 ~
72 : FD_CHECKPT_PRIVATE_CSZ_MAX( FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX ) */
73 :
74 6 : #define FD_CHECKPT_WBUF_MIN (69632UL) /* 68 KiB */
75 :
76 : /* FD_CHECKPT_{ALIGN,FOOTPRINT} give the required {alignment,footprint}
77 : of a memory region suitable for use as a fd_checkpt_t. */
78 :
79 : #define FD_CHECKPT_ALIGN alignof( fd_checkpt_t )
80 : #define FD_CHECKPT_FOOTPRINT sizeof( fd_checkpt_t )
81 :
82 : /* A fd_checkpt_t is a semi-opaque handle for an in-progress checkpoint
83 : (a stack or global declaration of an fd_checkpt_t is sufficient to
84 : get the correct alignment and footprint). */
85 :
86 : struct fd_checkpt_private;
87 : typedef struct fd_checkpt_private fd_checkpt_t;
88 :
89 : /* FD_RESTORE_RBUF_MIN is the minimum read buffer size needed by a
90 : fd_restore_t in streaming mode. Must be at least
91 : FD_CHECKPT_WBUF_MIN. */
92 :
93 3 : #define FD_RESTORE_RBUF_MIN FD_CHECKPT_WBUF_MIN
94 :
95 : /* FD_RESTORE_{ALIGN,FOOTPRINT} give the required {alignment,footprint}
96 : of a memory region suitable for use as a fd_restore_t. */
97 :
98 : #define FD_RESTORE_ALIGN alignof( fd_restore_t )
99 : #define FD_RESTORE_FOOTPRINT sizeof( fd_restore_t )
100 :
101 : /* A fd_restore_t is a semi-opaque handle of an in-progress restore (a
102 : stack or global declaration of an fd_restore_t is sufficient to get
103 : the correct alignment and footprint). */
104 :
105 : struct fd_restore_private;
106 : typedef struct fd_restore_private fd_restore_t;
107 :
108 : /* Internal use only **************************************************/
109 :
110 : /* These are exposed to facilitate things like stack declaration */
111 :
112 : /* FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX is the maximum amount of checkpt
113 : data fed into the underlying compressor at a time. Should be much
114 : less than LZ4_MAX_INPUT_SIZE (and probably much less than 2^24-1).
115 : 64 KiB is recommended. */
116 :
117 10083681 : #define FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX (65536UL)
118 :
119 : /* FD_CHECKPT_PRIVATE_CSZ_MAX returns a reasonably tight upper bound to
120 : the number of compressed output bytes generated given usz
121 : uncompressed input bytes. Assumes usz is safe against multiple
122 : evaluation and usz<=FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX. (This is the
123 : same as LZ4_COMPRESSBOUND plus 3 extra bytes for checkpt related
124 : metadata plus ulong typing usz and the usz limit.) */
125 :
126 836910 : #define FD_CHECKPT_PRIVATE_CSZ_MAX(usz) ((usz) + ((usz)/255UL) + 19UL)
127 :
128 : FD_STATIC_ASSERT( FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX <= (1UL<<30), adjust_comp_limits );
129 : FD_STATIC_ASSERT( FD_CHECKPT_WBUF_MIN >= FD_CHECKPT_PRIVATE_CSZ_MAX( FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX ), adjust_buf_limits );
130 : FD_STATIC_ASSERT( FD_RESTORE_RBUF_MIN >= FD_CHECKPT_WBUF_MIN, adjust_buf_limits );
131 :
132 : /* FD_CHECKPT_PRIVATE_GBUF_THRESH is byte size at which checkpt buffer
133 : is considered too large for small buffer checkpt gather
134 : optimizations. Should be at most FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX.
135 : Set to 0 to disable checkpt small gather optimization. */
136 :
137 6722454 : #define FD_CHECKPT_PRIVATE_GBUF_THRESH FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX
138 :
139 : /* FD_CHECKPT_PRIVATE_GBUF_SZ is the size of the checkpt gather buffer.
140 : Must be at least 2*THRESH + 65536 - 3 (the 64KiB is from LZ4). */
141 :
142 3361227 : #define FD_CHECKPT_PRIVATE_GBUF_SZ (2UL*FD_CHECKPT_PRIVATE_GBUF_THRESH + 65536UL)
143 :
144 : FD_STATIC_ASSERT( FD_CHECKPT_PRIVATE_GBUF_THRESH <= FD_CHECKPT_PRIVATE_CHUNK_USZ_MAX, adjust_gbuf_limits );
145 : FD_STATIC_ASSERT( FD_CHECKPT_PRIVATE_GBUF_SZ >= 2UL*FD_CHECKPT_PRIVATE_GBUF_THRESH + 65533UL, adjust_gbuf_limits );
146 :
147 : /* FD_RESTORE_PRIVATE_SBUF_{THRESH,SZ} similarly give the configuration
148 : for small buffer restore scatter optimizations. These currently need
149 : to match the gather configuration. */
150 :
151 1679433 : #define FD_RESTORE_PRIVATE_SBUF_THRESH FD_CHECKPT_PRIVATE_GBUF_THRESH
152 1679433 : #define FD_RESTORE_PRIVATE_SBUF_SZ FD_CHECKPT_PRIVATE_GBUF_SZ
153 :
154 : /* fd_checkpt_t internals */
155 :
156 : struct fd_checkpt_private_wbuf { /* very similar to fd_io_buffered_ostream */
157 : uchar * mem; /* Buffer of compressed bytes not yet written to fd, byte indexed [0,wbuf_sz) */
158 : ulong sz; /* Buffer size in bytes, >=FD_CHECKPT_WBUF_MIN */
159 : ulong used; /* Buffer bytes [0,wbuf_used) are not yet written to fd,
160 : buffer bytes [wbuf_used,wbuf_sz) are free */
161 : };
162 :
163 : typedef struct fd_checkpt_private_wbuf fd_checkpt_private_wbuf_t;
164 :
165 : struct fd_checkpt_private_mmio {
166 : uchar * mem; /* Checkpoint memory region */
167 : ulong sz; /* Checkpoint memory region byte size */
168 : };
169 :
170 : typedef struct fd_checkpt_private_mmio fd_checkpt_private_mmio_t;
171 :
172 : struct fd_checkpt_private {
173 : int fd; /* (stream) File descriptor for the checkpt (>=0), (mmio) -1 */
174 : int frame_style; /* FD_CHECKPT_FRAME_STYLE_* (>0), 0: not in frame (valid), -1: not in frame (failed) */
175 : void * lz4; /* Handle of the underlying compressor */
176 : ulong gbuf_cursor; /* Cursor for small buffer gather optimizations, in [0,FD_CHECKPT_PRIVATE_GBUF_SZ] */
177 : ulong off; /* Offset of the next byte to write (relative to the checkpoint first byte), in [0,mmio_sz) in mmio mode */
178 : union {
179 : fd_checkpt_private_wbuf_t wbuf; /* used in streaming mode */
180 : fd_checkpt_private_mmio_t mmio; /* used in mmio mode */
181 : };
182 : uchar gbuf[ FD_RESTORE_PRIVATE_SBUF_SZ ]; /* gather optimization buffer */
183 : };
184 :
185 : /* fd_restore_t internals */
186 :
187 : struct fd_restore_private_rbuf { /* very similar to fd_io_buffered_istream */
188 : uchar * mem; /* Buffer of compressed bytes read from fd, byte indexed [0,rbuf_sz) */
189 : ulong sz; /* Buffer size in bytes, >=FD_RESTORE_RBUF_MIN */
190 : ulong lo; /* Buffer bytes [0,rbuf_lo) have been read and restored */
191 : ulong ready; /* Number of compressed bytes that haven't been processed, 0<=rbuf_lo<=(rbuf_lo+rbuf_ready)<=rbuf_sz */
192 : };
193 :
194 : typedef struct fd_restore_private_rbuf fd_restore_private_rbuf_t;
195 :
196 : struct fd_restore_private_mmio {
197 : uchar const * mem; /* Checkpoint memory region */
198 : ulong sz; /* Checkpoint memory region size in bytes */
199 : ulong off; /* Offset of next byte to process relative to mmio, in [0,mmio_sz) */
200 : };
201 :
202 : typedef struct fd_restore_private_mmio fd_restore_private_mmio_t;
203 :
204 : struct fd_restore_private {
205 : int fd; /* (stream) File descriptor for the restore (>=0), (mmio) -1 */
206 : int frame_style; /* FD_CHECKPT_FRAME_STYLE_* (>0), 0: not in frame (valid), -1: not in frame (failed) */
207 : void * lz4; /* Handle of the underlying decompressor used */
208 : ulong sbuf_cursor; /* Cursor for small buffer scatter optimizations, in [0,FD_RESTORE_PRIVATE_SBUF_SZ] */
209 : union {
210 : fd_restore_private_rbuf_t rbuf; /* used in streaming mode */
211 : fd_restore_private_mmio_t mmio; /* used in mmio mode */
212 : };
213 : uchar sbuf[ FD_RESTORE_PRIVATE_SBUF_SZ ]; /* scatter optimization buffer */
214 : };
215 :
216 : FD_PROTOTYPES_BEGIN
217 :
218 : /* fd_{checkpt,restore}_private_is_mmio returns 0/1 if in streaming/mmio
219 : mode. Assumes {checkpt,restore} is valid. */
220 :
221 3567138 : FD_FN_PURE static inline int fd_checkpt_private_is_mmio( fd_checkpt_t const * checkpt ) { return checkpt->fd<0; }
222 3158934 : FD_FN_PURE static inline int fd_restore_private_is_mmio( fd_restore_t const * restore ) { return restore->fd<0; }
223 :
224 : /* fd_checkpt_private_{can_open,in_frame} returns 1 if {a frame can be
225 : opened,the checkpt is in a frame} and 0 otherwise. A failed checkpt
226 : is not in a frame but cannot open a new frame. Assumes checkpt is
227 : valid. Similarly for restore. */
228 :
229 407451 : FD_FN_PURE static inline int fd_checkpt_private_can_open( fd_checkpt_t const * checkpt ) { return !checkpt->frame_style; }
230 407349 : FD_FN_PURE static inline int fd_restore_private_can_open( fd_restore_t const * restore ) { return !restore->frame_style; }
231 :
232 3991677 : FD_FN_PURE static inline int fd_checkpt_private_in_frame( fd_checkpt_t const * checkpt ) { return checkpt->frame_style>0; }
233 3990705 : FD_FN_PURE static inline int fd_restore_private_in_frame( fd_restore_t const * restore ) { return restore->frame_style>0; }
234 :
235 : FD_PROTOTYPES_END
236 :
237 : /* End internal use only **********************************************/
238 :
239 : FD_PROTOTYPES_BEGIN
240 :
241 : /* Checkpt APIs *******************************************************/
242 :
243 : /* fd_checkpt_init_stream formats a memory region, mem, with suitable
244 : alignment and footprint into a fd_checkpt_t (a pointer to a stack
245 : declared fd_checkpt_t is fine). fd is an open normal-ish file
246 : descriptor where the checkpoint should be streamed out. wbuf points
247 : to the first byte in the caller's address space to an unused wbuf_sz
248 : byte size memory region to use for write buffering. wbuf_sz should
249 : be at least FD_CHECKPT_WBUF_MIN.
250 :
251 : On success, returns mem formatted as a fd_checkpt_t in streaming
252 : mode. On return, the fd_checkpt_t will be valid, not in a frame and
253 : will have ownership of mem, fd, and wbuf.
254 :
255 : On failure, returns NULL (logs details). No ownership changed. */
256 :
257 : fd_checkpt_t *
258 : fd_checkpt_init_stream( void * mem,
259 : int fd,
260 : void * wbuf,
261 : ulong wbuf_sz );
262 :
263 : /* fd_checkpt_init_mmio is the same as fd_checkpt_init_stream but
264 : checkpoints frames into a mmio_sz byte sized memory region whose
265 : first byte in the caller's the local address space is pointed to by
266 : mmio. */
267 :
268 : fd_checkpt_t *
269 : fd_checkpt_init_mmio( void * mem,
270 : void * mmio,
271 : ulong mmio_sz );
272 :
273 : /* fd_checkpt_fini finishes a checkpoint. checkpt should be valid and
274 : not in a frame.
275 :
276 : On success, returns mem. On return, checkpt is no longer valid and
277 : the caller will have ownership of mem, fd and wbuf (streaming mode)
278 : or mem and mmio (mmio mode).
279 :
280 : On failure, returns NULL (logs details). Reasons for failure include
281 : NULL checkpt and checkpt in a frame. The checkpt (and underlying fd
282 : in streaming mode) should be considered failed (i.e. checkpt no
283 : longer has any interest in checkpointed data and the user should only
284 : fini checkpt, close fd in streaming mode and discard the failed
285 : checkpoint). */
286 :
287 : void *
288 : fd_checkpt_fini( fd_checkpt_t * checkpt );
289 :
290 : /* fd_checkpt_frame_open_advanced opens a new frame. Different frames
291 : in a checkpoint can be restored in parallel. frame_style is a
292 : FD_CHECKPT_FRAME_STYLE_* that specifies the style of frame to output
293 : (0 indicates to use FD_CHECKPT_FRAME_STYLE_DEFAULT). checkpt should
294 : be valid and openable (not currently in a frame or failed).
295 :
296 : On success, returns FD_CHECKPT_SUCCESS (0). On return, *_off will
297 : contain the offset of this frame from the beginning of the
298 : checkpoint. This is to allow parallel restore threads to jump to
299 : frames they are assigned to restore. Retains no interest in _off.
300 :
301 : On failure, logs details and returns a FD_CHECKPT_ERR (negative).
302 : *_off will be untouched. Retains no interest in _off. Reasons for
303 : failure include INVAL (NULL checkpt, in a frame, failed), UNSUP
304 : (unsupported frame style on this target), IO (an i/o error) and COMP
305 : (a compressor error). The checkpt (and underlying fd in streaming
306 : mode) should be considered failed (i.e. the checkpt no longer has
307 : any interest in checkpointed data and the user should only fini
308 : checkpt, close fd in streaming mode and discard the failed
309 : checkpoint).
310 :
311 : IMPORTANT SAFETY TIP! The returned offset is relative to the start
312 : of the _checkpoint_, _not_ the start of the _file_. These are often
313 : the same but do not have to be (e.g. writing a checkpoint to an
314 : unseekable file descriptor like stdout, the caller has already
315 : written other data to the file descriptor before starting the
316 : checkpoint, etc).
317 :
318 : IMPORTANT SAFETY TIP! Compression ratios for compressed frames can
319 : optimized by putting similar items into the same frame and then
320 : putting more similar items near each other sequentially.
321 :
322 : fd_checkpt_frame_open is a convenience for when the frame offset
323 : isn't needed (makes API exactly symmetric with fd_restore). */
324 :
325 : int
326 : fd_checkpt_frame_open_advanced( fd_checkpt_t * checkpt,
327 : int frame_style,
328 : ulong * _off );
329 :
330 : static inline int
331 : fd_checkpt_frame_open( fd_checkpt_t * checkpt,
332 48 : int frame_style ) {
333 48 : ulong off;
334 48 : return fd_checkpt_frame_open_advanced( checkpt,frame_style, &off );
335 48 : }
336 :
337 : /* fd_checkpt_frame_close_advanced closes the current frame. checkpt
338 : should be valid and in a frame.
339 :
340 : On success, returns FD_CHECKPT_SUCCESS (0). On return, *_off will
341 : contain the offset of one past the last byte of the just closed
342 : frame. That is, [off_open,off_close) specify the range bytes
343 : relative to the start of the checkpoint used by this frame and
344 : off_close-off_open is the frame byte size. This is to facilitate
345 : parallel checkpoint writing and then concatentating results from
346 : different threads into a compact checkpoint. checkpt will no longer
347 : have any interest in checkpointed data or in _off.
348 :
349 : On failure, logs details and returns a FD_CHECKPT_ERR (negative). On
350 : return, *_off will be untouched and checkpoint will have no inteest
351 : in _off. Reasons for failure include INVAL (NULL checkpt, not in a
352 : frame), IO (write failed, too many bytes written) and COMP (a
353 : compressor error). The checkpt (and underlying fd in streaming mode)
354 : should be considered failed (i.e. the checkpt no longer has any
355 : interest in checkpointed data and the user should only fini checkpt,
356 : close fd in streaming mode and discard the failed checkpoint).
357 :
358 : fd_checkpt_frame_close is a convenience for when the frame offset
359 : isn't needed. */
360 :
361 : int
362 : fd_checkpt_frame_close_advanced( fd_checkpt_t * checkpt,
363 : ulong * _off );
364 :
365 : static inline int
366 24 : fd_checkpt_frame_close( fd_checkpt_t * checkpt ) {
367 24 : ulong off;
368 24 : return fd_checkpt_frame_close_advanced( checkpt, &off );
369 24 : }
370 :
371 : /* fd_checkpt_buf checkpoints the sz byte memory region whose first byte
372 : in the caller's local address space is pointed to by buf. checkpt
373 : should be valid and in a frame. sz==0 is fine (and buf==NULL if
374 : sz==0 is also fine).
375 :
376 : On success, returns FD_CHECKPT_SUCCESS (0). IMPORTANT SAFETY TIP!
377 : checkpt retains an interest in buf until the frame is closed (e.g.
378 : buf should continue to exist unchanged until the frame is closed).
379 : AMONG OTHER THINGS, THIS MEANS IT IS UNSAFE TO GATHER DATA INTO A
380 : TEMP BUFFER, CHECKPT THE TEMP BUFFER AND THEN FREE / REUSE THAT TEMP
381 : BUFFER BEFORE THE FRAME IS CLOSED!
382 :
383 : On failure, logs details and returns a FD_CHECKPT_ERR (negative).
384 : Reasons for failure include INVAL (NULL checkpt, not in a frame, NULL
385 : buf with a non-zero sz), IO (write failed, too many bytes written)
386 : and COMP (compressor error). The checkpt (and underlying fd in
387 : streaming mode) should be considered failed (i.e. should only fini
388 : checkpt, close fd in streaming mode and discard the failed
389 : checkpoint). */
390 :
391 : int
392 : fd_checkpt_buf( fd_checkpt_t * checkpt,
393 : void const * buf,
394 : ulong sz );
395 :
396 : /* Restore APIs *******************************************************/
397 :
398 : /* fd_restore_init_stream formats a memory region, mem, with suitable
399 : alignment and footprint into a fd_restore_t in streaming mode (a
400 : pointer to a stack declared fd_restore_t is fine). fd is an open
401 : normal-ish file descriptor positioned at the start of the first
402 : checkpoint frame to read. rbuf points to the first byte in the
403 : caller's address space of an unused rbuf_sz byte size memory region
404 : to use for read buffering. rbuf_sz should be at least
405 : FD_RESTORE_RBUF_MIN (it does _not_ need to match the wbuf_sz used to
406 : make the checkpoint).
407 :
408 : On success, returns mem formatted as a fd_restore_t. On return, the
409 : fd_restore_t will be valid, not in a frame and will have ownership of
410 : mem, fd, and rbuf.
411 :
412 : On failure, returns NULL (logs details). No ownership changed. */
413 :
414 : fd_restore_t *
415 : fd_restore_init_stream( void * mem,
416 : int fd,
417 : void * rbuf,
418 : ulong rbuf_sz );
419 :
420 : /* fd_restore_init_mmio is the same as fd_restore_init_stream but the
421 : frames to restore have been memory mapped into the mmio_sz byte
422 : memory region whose first byte in the caller's the local address
423 : space is pointed to by mmio. */
424 :
425 : fd_restore_t *
426 : fd_restore_init_mmio( void * mem,
427 : void const * mmio,
428 : ulong mmio_sz );
429 :
430 : /* fd_restore_fini finishes restoring from a checkpoint. restore should
431 : be valid and not in a frame.
432 :
433 : On success, returns mem. On return, restore is no longer valid and
434 : the caller will have ownership of mem, fd and rbuf (streaming mode)
435 : or mem and mmio (mmio mode).
436 :
437 : On failure, returns NULL (logs details). Reasons for failure include
438 : NULL restore and restore in a frame. The restore (and underlying fd
439 : in streaming mode) should be considered failed (i.e. the restore no
440 : longer has any interest in restored data and the user should only
441 : fini restore and close fd in streaming mode). */
442 :
443 : void *
444 : fd_restore_fini( fd_restore_t * restore );
445 :
446 : /* fd_restore_frame_open opens a new checkpoint frame. Different frames
447 : in a checkpoint can be restored in parallel. frame_style is a
448 : FD_CHECKPT_FRAME_STYLE_* that specifies the style of frame to read
449 : (0 indicates to use FD_CHECKPT_FRAME_STYLE_DEFAULT). restore should
450 : be valid and not currently in a frame.
451 :
452 : On success, returns FD_CHECKPT_SUCCESS (0).
453 :
454 : On failure, logs details and returns a FD_CHECKPT_ERR (negative).
455 : Reasons for failure include INVAL (NULL restore, in a frame, failed),
456 : UNSUP (unsupported frame style on this target), IO (an i/o error) and
457 : COMP (a decompressor error). The restore (and underlying fd in
458 : streaming mode) should be considered failed (i.e. the restore no
459 : longer has any interest in restored data and the user should only
460 : fini restore and close fd in streaming mode).
461 :
462 : IMPORTANT SAFETY TIP! frame_style should match the frame_style used
463 : to when the checkpoint was written.
464 :
465 : IMPORTANT SAFETY TIP! The sequence of restore_frame_open /
466 : restore_buf / restore_frame_close calls should _exactly_ match the
467 : sequence of checkpt_frame_open / checkpt_buf / checkpt_frame_close
468 : used when the frame was written. */
469 :
470 : int
471 : fd_restore_frame_open( fd_restore_t * restore,
472 : int frame_style );
473 :
474 : /* fd_restore_frame_close closes the current frame. restore should be
475 : valid and in a frame.
476 :
477 : On success, returns FD_CHECKPT_SUCCESS (0). The restore will no
478 : longer have any interest in restored data.
479 :
480 : On failure, logs details and returns a FD_CHECKPT_ERR (negative).
481 : Reasons for failure include INVAL (NULL restore, not in a frame), IO
482 : (an i/o error) and COMP (a decompressor error). The restore (and
483 : underlying fd in streaming mode) should be considered failed (i.e.
484 : the restore no longer has any interest in restored data and the user
485 : should only fini restore and close fd in streaming mode).
486 :
487 : IMPORTANT SAFETY TIP! The sequence of restore_frame_open /
488 : restore_buf / restore_frame_close calls should _exactly_ match the
489 : sequence of checkpt_frame_open / checkpt_buf / checkpt_frame_close
490 : used when the frame was created. */
491 :
492 : int
493 : fd_restore_frame_close( fd_restore_t * restore );
494 :
495 : /* fd_restore_buf restores sz bytes to the memory region whose first
496 : byte in the caller's local address space is pointed to by buf.
497 : restore should be valid and in a frame. sz==0 is fine (and buf==NULL
498 : if sz==0 is also fine).
499 :
500 : On success, returns FD_CHECKPT_SUCCESS (0). On return, buf will
501 : contain the restored data (FIXME: consider not guaranteeing
502 : availability of the restored buf until the frame is closed).
503 : IMPORTANT SAFETY TIP! restore retains an interest in buf until the
504 : frame is closed (e.g. buf should continue to exist unchanged until
505 : the frame is closed). AMONG OTHER THINGS, THIS IMPLIES RESTORE
506 : MEMORY REGIONS SHOULD NOT OVERLAP AND THAT IT IS UNSAFE TO RESTORE TO
507 : A TEMP BUFFER, SCATTER DATA FROM THE TEMP BUFFER AND THEN FREE /
508 : REUSE THAT TEMP BUFFER BEFORE THE FRAME IS CLOSED!
509 :
510 : On failure, logs details and returns a FD_CHECKPT_ERR (negative).
511 : Reasons for failure include INVAL (NULL restore, not in a frame, NULL
512 : buf with a non-zero sz), IO (read failed, too many bytes read) and
513 : COMP (a decompressor error). The restore (and underlying fd in
514 : streaming mode) should be considered failed (i.e. the restore no
515 : longer has any interest in restored data and the user should only
516 : fini restore and close fd in streaming mode).
517 :
518 : IMPORTANT SAFETY TIP! The sequence of restore_frame_open /
519 : restore_buf / restore_frame_close calls should _exactly_ match the
520 : sequence of checkpt_frame_open / checkpt_buf / checkpt_frame_close
521 : used when the frame was created. */
522 :
523 : int
524 : fd_restore_buf( fd_restore_t * restore,
525 : void * buf,
526 : ulong sz );
527 :
528 : /* Misc APIs **********************************************************/
529 :
530 : /* fd_checkpt_strerror converts an FD_CHECKPT_SUCCESS / FD_CHECKPT_ERR_*
531 : code into a human readable cstr. The lifetime of the returned
532 : pointer is infinite. The returned pointer is always to a non-NULL
533 : cstr. */
534 :
535 : char const *
536 : fd_checkpt_strerror( int err );
537 :
538 : FD_PROTOTYPES_END
539 :
540 : #endif /* HEADER_fd_src_util_checkpt_fd_checkpt_h */
|
