Line data Source code
1 : #ifndef HEADER_fd_src_vinyl_io_fd_vinyl_io_h
2 : #define HEADER_fd_src_vinyl_io_fd_vinyl_io_h
3 :
4 : /* A fd_vinyl_io_t reads from / appends to a bstream stored in some
5 : physical layer (typically slow and non-volatile). Supports massive
6 : numbers of async concurrent reads and appends and the ability to
7 : recover from unexpected interrupts (Ctrl-C, power failures, etc). To
8 : accommodate the myriad of different styles of physical layers and
9 : interfaces, the API is run time plugin friendly. Summary of
10 : operations:
11 :
12 : read_imm: blocking read a contiguous range of blocks in the
13 : bstream's past. Mostly used for iterating over a bstream's past.
14 :
15 : read: start reading a contiguous range of blocks in the bstream's
16 : past. The caller promises the range to read is contiguous in the
17 : underlying physical storage.
18 :
19 : poll: finish an outstanding read. Outstanding reads can complete
20 : in an arbitrary order. All reads must be finished by poll but note
21 : that it is possible to detect a read is complete out-of-band too
22 : (for speculative processing).
23 :
24 : append: start appending a set of blocks to the end of the bstream's
25 : present (moving blocks from the bstream's future to the bstream's
26 : present). The blocks will be contiguous in the underlying storage.
27 : The blocks must be suitably aligned and with a lifetime until the
28 : next commit.
29 :
30 : commit: finish all outstanding appends, moving all blocks in the
31 : bstream's present to the bstream's past. This will empty the io's
32 : append scratch pad. The underlying implementation is free to
33 : process outstanding appends in any order (and free to interleave
34 : them arbitrarily with outstanding reads).
35 :
36 : hint: indicates the next sz worth of blocks appended to the bstream
37 : must be contiguous in the physical storage.
38 :
39 : alloc: allocate memory from the io's append scratch pad. These
40 : allocations will have a suitable alignment for append and a
41 : lifetime until the next commit. This may trigger a commit of
42 : outstanding appends if there isn't enough scratch pad free.
43 :
44 : copy: append a contiguous range of blocks from the bstream's past
45 : to the end of the bstream's present. May commit outstanding
46 : appends.
47 :
48 : forget: forget all blocks before a given sequence number, moving
49 : blocks from the bstream's past to the bstream's antiquity. The
50 : caller can only forget up to the bstream's present.
51 :
52 : rewind: move blocks from the bstream's past (and potentially
53 : antiquity) to the bstream's future. The bstream must have an empty
54 : present (i.e. no appends in progress) and no reads in progress.
55 : This allows, for example, on recovery, a multi-block pair that was
56 : incompletely written to be cleaned up.
57 :
58 : sync: update the range for the bstream past where recovery will
59 : resume. This moves all blocks in the bstream's antiquity to end of
60 : the bstream's future. */
61 :
62 : /* FIXME: consider a query to get how many reads are outstanding? (with
63 : this, rewind and forget could be complete generic). */
64 :
65 : #include "../bstream/fd_vinyl_bstream.h"
66 :
67 : /* FD_VINYL_IO_TYPE_* identifies which IO implementation is in use. */
68 :
69 9 : #define FD_VINYL_IO_TYPE_MM (0) /* memory mapped */
70 9 : #define FD_VINYL_IO_TYPE_BD (1) /* synchronous blocking */
71 : #define FD_VINYL_IO_TYPE_WD (2) /* async O_DIRECT write (specialized) */
72 : #define FD_VINYL_IO_TYPE_UR (3) /* async io_uring */
73 :
74 : /* FD_VINYL_IO_FLAG_* are flags used by various vinyl IO APIs */
75 :
76 1497300 : #define FD_VINYL_IO_FLAG_BLOCKING (1) /* Okay to block the caller */
77 :
78 : /* A fd_vinyl_io_rd_t describes a read request to the underlying I/O
79 : implementation to read [seq,seq+sz) (cyclic) from the bstream's past
80 : into dst. seq, dst and sz should be FD_VINYL_BSTREAM_BLOCK_SZ
81 : aligned. Any failure encountered while reading should FD_LOG_CRIT
82 : (just like reading an invalid memory address will seg fault).
83 : Underlying I/O implementations can add other information to this
84 : structure as necessary. ctx is an arbitrary user defined value. */
85 :
86 : #define FD_VINYL_IO_READ_SZ (64UL)
87 :
88 : struct fd_vinyl_io_rd {
89 : ulong ctx;
90 : ulong seq;
91 : void * dst;
92 : ulong sz;
93 : uchar _[ FD_VINYL_IO_READ_SZ - 32UL ];
94 : };
95 :
96 : typedef struct fd_vinyl_io_rd fd_vinyl_io_rd_t;
97 :
98 : /* fd_vinyl_io_t is an opaque handle of a fd_vinyl_io instance. Some
99 : details are exposed to facilitate inlining in high performance
100 : contexts. */
101 :
102 : struct fd_vinyl_io_private;
103 : typedef struct fd_vinyl_io_private fd_vinyl_io_t;
104 :
105 : typedef void (*fd_vinyl_io_func_read_imm_t)( fd_vinyl_io_t * io, ulong seq, void * dst, ulong sz );
106 : typedef void (*fd_vinyl_io_func_read_t )( fd_vinyl_io_t * io, fd_vinyl_io_rd_t * rd );
107 : typedef int (*fd_vinyl_io_func_poll_t )( fd_vinyl_io_t * io, fd_vinyl_io_rd_t ** _rd, int flags );
108 : typedef ulong (*fd_vinyl_io_func_append_t )( fd_vinyl_io_t * io, void const * src, ulong sz );
109 : typedef int (*fd_vinyl_io_func_commit_t )( fd_vinyl_io_t * io, int flags );
110 : typedef ulong (*fd_vinyl_io_func_hint_t )( fd_vinyl_io_t * io, ulong sz );
111 : typedef void * (*fd_vinyl_io_func_alloc_t )( fd_vinyl_io_t * io, ulong sz, int flags );
112 : typedef ulong (*fd_vinyl_io_func_copy_t )( fd_vinyl_io_t * io, ulong seq, ulong sz );
113 : typedef void (*fd_vinyl_io_func_forget_t )( fd_vinyl_io_t * io, ulong seq );
114 : typedef void (*fd_vinyl_io_func_rewind_t )( fd_vinyl_io_t * io, ulong seq );
115 : typedef int (*fd_vinyl_io_func_sync_t )( fd_vinyl_io_t * io, int flags );
116 : typedef void * (*fd_vinyl_io_func_fini_t )( fd_vinyl_io_t * io );
117 :
118 : struct fd_vinyl_io_impl {
119 : fd_vinyl_io_func_read_imm_t read_imm;
120 : fd_vinyl_io_func_read_t read;
121 : fd_vinyl_io_func_poll_t poll;
122 : fd_vinyl_io_func_append_t append;
123 : fd_vinyl_io_func_commit_t commit;
124 : fd_vinyl_io_func_hint_t hint;
125 : fd_vinyl_io_func_alloc_t alloc;
126 : fd_vinyl_io_func_copy_t copy;
127 : fd_vinyl_io_func_forget_t forget;
128 : fd_vinyl_io_func_rewind_t rewind;
129 : fd_vinyl_io_func_sync_t sync;
130 : fd_vinyl_io_func_fini_t fini;
131 : };
132 :
133 : typedef struct fd_vinyl_io_impl fd_vinyl_io_impl_t;
134 :
135 : struct fd_vinyl_io_private {
136 : int type;
137 : ulong seed;
138 : ulong seq_ancient; /* FD_VINYL_BSTREAM_BLOCK_SZ multiple */
139 : ulong seq_past; /* " */
140 : ulong seq_present; /* " */
141 : ulong seq_future; /* " */
142 : ulong spad_max; /* " */
143 : ulong spad_used; /* " */
144 : fd_vinyl_io_impl_t * impl; /* implementation specific funcs */
145 : /* io implementation specific details follow */
146 : };
147 :
148 : FD_PROTOTYPES_BEGIN
149 :
150 : /* fd_vinyl_io_* return the current value of the eponymous io field.
151 : Assumes io is valid. For all but type and seed, the return value is
152 : a FD_VINYL_BSTREAM_BLOCK_SZ multiple. Note that we don't have a
153 : generic notion of dev_max or dev_free as such is not a well defined
154 : concept. Individual IO implementations can provide them as
155 : appropriate though. */
156 :
157 12 : FD_FN_PURE static inline int fd_vinyl_io_type( fd_vinyl_io_t const * io ) { return io->type; }
158 :
159 12 : FD_FN_PURE static inline ulong fd_vinyl_io_seed( fd_vinyl_io_t const * io ) { return io->seed; }
160 :
161 12000012 : FD_FN_PURE static inline ulong fd_vinyl_io_seq_ancient( fd_vinyl_io_t const * io ) { return io->seq_ancient; }
162 12000012 : FD_FN_PURE static inline ulong fd_vinyl_io_seq_past ( fd_vinyl_io_t const * io ) { return io->seq_past; }
163 12000012 : FD_FN_PURE static inline ulong fd_vinyl_io_seq_present( fd_vinyl_io_t const * io ) { return io->seq_present; }
164 12000012 : FD_FN_PURE static inline ulong fd_vinyl_io_seq_future ( fd_vinyl_io_t const * io ) { return io->seq_future; }
165 :
166 2970 : FD_FN_PURE static inline ulong fd_vinyl_io_spad_max ( fd_vinyl_io_t const * io ) { return io->spad_max; }
167 2970 : FD_FN_PURE static inline ulong fd_vinyl_io_spad_used( fd_vinyl_io_t const * io ) { return io->spad_used; }
168 2970 : FD_FN_PURE static inline ulong fd_vinyl_io_spad_free( fd_vinyl_io_t const * io ) { return io->spad_max - io->spad_used; }
169 :
170 0 : FD_FN_PURE static inline ulong fd_vinyl_io_dev_used( fd_vinyl_io_t const * io ) { return io->seq_future - io->seq_ancient; }
171 :
172 : /* fd_vinyl_io_read_imm does an immediate (blocking) read of
173 : [seq,seq+dst_sz) (cyclic) from io's bstream's past into dst. Assumes
174 : there are no reads currently posted on io. Retains no interest in
175 : dst. seq and sz should be FD_VINYL_BSTREAM_BLOCK_SZ aligned. This
176 : is used mostly for sequential iterating over a bstream's past (i.e.
177 : serial recovery and discovering partitions for parallel recovery). */
178 :
179 : static inline void
180 : fd_vinyl_io_read_imm( fd_vinyl_io_t * io,
181 : ulong seq,
182 : void * dst,
183 2998734 : ulong sz ) {
184 2998734 : io->impl->read_imm( io, seq, dst, sz );
185 2998734 : }
186 :
187 : /* fd_vinyl_io_read starts the executing the read command rd. That is,
188 : start reading bstream bytes [seq,seq+sz) (cyclic) into dst. seq and
189 : sz should be FD_VINYL_BSTREAM_BLOCK_SZ aligned. Further,
190 : [seq,seq+sz) should be in the bstream's past and the region to read
191 : should be stored contiguously in the underlying storage.
192 :
193 : On entry, the caller should have ownership of rd and rd->dst. The io
194 : has ownership of these return and a read interest in bstream bytes
195 : [seq,seq_sz) (cyclic). The ownership of these will be returned to
196 : the caller and the read interest will end when poll returns the
197 : request. */
198 :
199 : static inline void
200 : fd_vinyl_io_read( fd_vinyl_io_t * io,
201 3748140 : fd_vinyl_io_rd_t * rd ) {
202 3748140 : io->impl->read( io, rd );
203 3748140 : }
204 :
205 : /* fd_vinyl_io_poll checks if any outstanding reads are complete. Reads
206 : can complete in any order by the I/O layer. flags is a bit-or of
207 : FD_VINYL_IO_FLAGs. BLOCKING indicates the call is allowed to block
208 : the caller (the io layer promises the call cannot fail from the
209 : caller's point of view). Returns FD_VINYL_SUCCESS if a read complete
210 : (*_rd will point to the read command ended with the ownership and
211 : read interested as described above), FD_VINYL_ERR_EMPTY if there are
212 : no commands pending (*_rd will be NULL) and FD_VINYL_ERR_AGAIN if
213 : none of the posted commands are ready (*_rd will be NULL). AGAIN is
214 : only possible for a non-blocking call). */
215 :
216 : static inline int
217 : fd_vinyl_io_poll( fd_vinyl_io_t * io,
218 : fd_vinyl_io_rd_t ** _rd,
219 7496280 : int flags ) {
220 7496280 : return io->impl->poll( io, _rd, flags );
221 7496280 : }
222 :
223 : /* fd_vinyl_io_append starts appending sz bytes at src to the bstream.
224 : src and sz should be FD_VINYL_BSTREAM_BLOCK_SZ aligned. Returns
225 : bstream sequence number seq_append where the data is being appended.
226 : io will have a read interest in src until the next commit. This
227 : moves blocks from the bstream's future to the bstream's present. On
228 : commit, the region [seq_future_before,seq_append) (cyclic) will be
229 : filled with zero padding if the I/O implementation requires it to
230 : keep the append contiguous in the physical store (this region will be
231 : empty if covered by a previous hint or if this is an append of a
232 : single block) and the region [seq_append,seq_future_after) (cyclic)
233 : will be filled with the appended info.
234 :
235 : fd_vinyl_io_commit moves all blocks in the bstream's present to the
236 : bstream's past (i.e. sets seq_present to seq_future). flags is a
237 : bit-of FD_VINYL_IO_FLAGs. If BLOCKING is set, this is allowed to
238 : block the caller. Returns FD_VINYL_SUCCESS (0) on success and
239 : FD_VINYL_ERR_AGAIN (negative) if commit could not be completed
240 : immediately (only possible for a non-blocking call). commit empties
241 : the io append scratch pad on success.
242 :
243 : fd_vinyl_io_hint indicates the next sz bytes to append must be
244 : contiguous in the bstream. This can move blocks from the bstream's
245 : future to the bstream's present. Returns (the potentially updated)
246 : seq_future. On commit, the region
247 : [seq_future_before,seq_future_after) (cyclic) will be filled with
248 : zero padding (this region will be empty if covered by a previous
249 : hint) and the region [seq_future_after,seq_future_after+sz) (cyclic)
250 : will contiguous in the physical storage. This is useful for grouping
251 : sets of blocks from different memory regions on the host that must be
252 : written contiguously from a protocol point of view (e.g. a move
253 : control block and the pair that follows it).
254 :
255 : fd_vinyl_io_alloc returns a pointer to sz bytes of
256 : FD_VINYL_BSTREAM_BLOCK_SZ aligned memory suitable allocated from io's
257 : append scratch pad. flags is a bit-or FD_VINYL_IO_FLAG_*. BLOCKING
258 : indicates the call is allowed to block the caller. If a non-blocking
259 : call, will return NULL if there is no suitable memory at this time.
260 : Will never return NULL for a blocking call. The lifetime of the
261 : returned pointer is the lesser of the next append, next commit, the
262 : next alloc or the io. sz should be FD_VINYL_BSTREAM_BLOCK_SZ aligned
263 : and at most io's spad_max. This may do a commit to free up scratch
264 : pad memory if necessary (moving blocks from the present to the past).
265 :
266 : fd_vinyl_io_trim trims sz bytes from the end of the most recent
267 : fd_vinyl_io_alloc. sz should be FD_VINYL_BSTREAM_BLOCK_SZ aligned
268 : and at most the size of the most recent alloc.
269 :
270 : fd_vinyl_io_copy starts appending a copy of the sz bytes at seq in
271 : the bstream's past to the bstream. seq and sz should be
272 : FD_VINYL_BSTREAM_BLOCK_SZ aligned. [seq,seq+sz) (cyclic) should be
273 : in the bstream's past. io will have a read interest in this region
274 : until the next commit. This will do a _blocking_ commit to free up
275 : scratch pad memory if necessary (moving blocks from the present to
276 : the past). FIXME: consider non-blocking copy support? (copy would
277 : need a flags args).
278 :
279 : None of these can fail from the caller's perspective (they will all
280 : FD_LOG_CRIT if anything goes wrong ... much like accessing invalid
281 : memory will seg fault). */
282 :
283 : static inline ulong
284 : fd_vinyl_io_append( fd_vinyl_io_t * io,
285 : void const * src,
286 750210 : ulong sz ) {
287 750210 : return io->impl->append( io, src, sz );
288 750210 : }
289 :
290 : static inline int
291 : fd_vinyl_io_commit( fd_vinyl_io_t * io,
292 749004 : int flags ) {
293 749004 : return io->impl->commit( io, flags );
294 749004 : }
295 :
296 : static inline ulong
297 : fd_vinyl_io_hint( fd_vinyl_io_t * io,
298 753444 : ulong sz ) {
299 753444 : return io->impl->hint( io, sz );
300 753444 : }
301 :
302 : static inline void *
303 : fd_vinyl_io_alloc( fd_vinyl_io_t * io,
304 : ulong sz,
305 2964 : int flags ) {
306 2964 : return io->impl->alloc( io, sz, flags );
307 2964 : }
308 :
309 : static inline void
310 : fd_vinyl_io_trim( fd_vinyl_io_t * io,
311 0 : ulong sz ) {
312 0 : io->spad_used -= sz;
313 0 : }
314 :
315 : static inline ulong
316 : fd_vinyl_io_copy( fd_vinyl_io_t * io,
317 : ulong seq,
318 752298 : ulong sz ) {
319 752298 : return io->impl->copy( io, seq, sz );
320 752298 : }
321 :
322 : /* fd_vinyl_io_forget moves [seq_past,seq) (cyclic) from the bstream's
323 : past to the bstream's antiquity, setting seq_past to seq. As such,
324 : seq should be in [seq_past,seq_present] (cyclic) and
325 : FD_VINYL_BSTREAM_BLOCK_SZ aligned. There should be no reads, copies
326 : or appends in progress. Cannot fail from the caller's perspective
327 : (will FD_LOG_CRIT if anything goes wrong).
328 :
329 : IMPORTANT SAFETY TIP! Though the bstream has been updated from the
330 : caller's point of view, the bstream needs to be sync'd for recover to
331 : start from the new seq_past. */
332 :
333 : static inline void
334 : fd_vinyl_io_forget( fd_vinyl_io_t * io,
335 263526 : ulong seq ) {
336 263526 : io->impl->forget( io, seq );
337 263526 : }
338 :
339 : /* fd_vinyl_io_rewind moves blocks [seq,seq_present) (cyclic) from the
340 : bstream's past to the bstream's future (updating seq_ancient and
341 : seq_past as necessary). There should be no reads, copies or appends
342 : in progress. seq should at most seq_present (cyclic) and
343 : FD_VINYL_BSTREAM_BLOCK_SZ aligned. Cannot fail from the caller's
344 : perspective (will FD_LOG_CRIT if anything goes wrong).
345 :
346 : IMPORTANT SAFETY TIP! Though the bstream has been updated from the
347 : caller's point of view, the bstream needs to be sync'd for recovery
348 : to account for the rewind (and this is probably more critical than
349 : forget because appends will start modifying the bstream blocks that
350 : recovery would be expecting to be in the pre-rewind state). */
351 :
352 : static inline void
353 : fd_vinyl_io_rewind( fd_vinyl_io_t * io,
354 213468 : ulong seq ) {
355 213468 : io->impl->rewind( io, seq );
356 213468 : }
357 :
358 : /* fd_vinyl_io_sync moves [seq_ancient,seq_past) (cyclic) from the
359 : bstream's antiquity to the end of the bstream's future, setting
360 : seq_ancient to seq_past. It promises the caller the bstream's past
361 : is fully written and that the bstream's past region is what recovery
362 : will use to recover the bstream's key-val state at seq_present.
363 : flags is a bit-or of FD_VINYL_IO_FLAGs. BLOCKING indicates the call
364 : is allowed to block the caller. Returns FD_VINYL_SUCCESS (0) on
365 : success and a FD_VINYL_ERR_AGAIN (negative) if the call would block
366 : the caller (only possible for a non-blocking call). */
367 : /* FIXME: consider allowing new user info to be passed? */
368 :
369 : static inline int
370 : fd_vinyl_io_sync( fd_vinyl_io_t * io,
371 748320 : int flags ) {
372 748320 : return io->impl->sync( io, flags );
373 748320 : }
374 :
375 : /* fd_vinyl_io_fini tears down io, returning the memory region used to
376 : hold the I/O implementation state. Implicitly completes any
377 : in-progress reads and cancels any in-progress appends (and thus can
378 : block the caller).
379 :
380 : IMPORTANT SAFETY TIP! This does _not_ sync the bstream first (e.g.
381 : if an application is tearing down due to an anomalous condition, it
382 : may not want to sync on fini so that it can recover from a known good
383 : point). */
384 :
385 : void *
386 : fd_vinyl_io_fini( fd_vinyl_io_t * io );
387 :
388 : /* Helpers ************************************************************/
389 :
390 : /* fd_vinyl_io_spad_est() returns estimate of the smallest scratch pad
391 : size required for most applications. Specifically, this returns:
392 :
393 : 2 pair_sz( LZ4_COMPRESSBOUND( VAL_MAX ) )
394 :
395 : so that it is possible to load a object footprint into the scratch
396 : pad and then have a worst case scratch memory for compression to
397 : re-encode the object. */
398 :
399 : FD_FN_CONST ulong fd_vinyl_io_spad_est( void );
400 :
401 : /* fd_vinyl_io_append_* are helper functions that start appending the
402 : given info, appropriately formatted and hashed, to io's bstream.
403 : There is no excess requirements for alignment. They do no input
404 : argument checking. On return, io retains no interest in the given
405 : info (that is, they use io's scratch memory and thus can trigger an
406 : io commit to move blocks from the bstream's present to the bstream's
407 : past if there isn't enough scratch pad free). They return the
408 : bstream sequence number where the data is being appended. They
409 : cannot fail from the caller's perspective (they will FD_LOG_CRIT if
410 : anything goes awry). */
411 :
412 : ulong
413 : fd_vinyl_io_append_pair_raw( fd_vinyl_io_t * io,
414 : fd_vinyl_key_t const * key, /* pair key */
415 : fd_vinyl_info_t const * info, /* pair info */
416 : void const * val ); /* contains info->val_sz bytes, in [0,FD_VINYL_VAL_MAX] */
417 :
418 : ulong
419 : fd_vinyl_io_append_dead( fd_vinyl_io_t * io,
420 : fd_vinyl_bstream_phdr_t const * phdr, /* pair header of erased pair */
421 : void const * info, /* contains info_sz bytes, info_sz treated as 0 if NULL */
422 : ulong info_sz ); /* in [0,FD_VINYL_BSTREAM_DEAD_INFO_MAX] */
423 :
424 : ulong
425 : fd_vinyl_io_append_move( fd_vinyl_io_t * io,
426 : fd_vinyl_bstream_phdr_t const * src, /* pair header of src pair */
427 : fd_vinyl_key_t const * dst, /* src pair getting renamed to dst or is replacing dst */
428 : void const * info, /* contains info_sz bytes, info_sz treated as 0 if NULL */
429 : ulong info_sz ); /* in [0,FD_VINYL_BSTREAM_MOVE_INFO_MAX] */
430 :
431 : ulong
432 : fd_vinyl_io_append_part( fd_vinyl_io_t * io,
433 : ulong seq_prev, /* should be a part before seq or seq */
434 : ulong dead_cnt, /* number of dead blocks in the partition */
435 : ulong move_cnt, /* number of move blocks in the partition */
436 : void const * info, /* contains info_sz bytes, info_sz treated as 0 if NULL */
437 : ulong info_sz ); /* in [0,FD_VINYL_BSTREAM_PART_INFO_MAX] */
438 :
439 : /* fd_vinyl_io_append_pair_inplace appends the style RAW pair at phdr
440 : to the bstream. This will preferentially append the pair in the
441 : given style. Returns the location where the pair was appended. On
442 : return, *_style holds the actual style used and *_val_esz contains
443 : the pair encoded value byte size.
444 :
445 : Note that if the requested style is RAW or if the pair could not be
446 : usefully encoded in the requested style (e.g. the compressed size
447 : ended up larger than the uncompressed size), this will append from
448 : phdr in-place zero copy. When appending a pair in-place, this will
449 : clear the zero padding region and insert the appropriate data
450 : integrity footers at the end of the pair. On other cases, this will
451 : append from the io append scratch memory the encoded pair and the
452 : pair will be untouched.
453 :
454 : As such, the caller should assume the io has a read interest on the
455 : pair's header region and value region and a write interest on the
456 : pair zero padding region and footer region until the next append or
457 : commit and the pair's zero padding and footer regions may be
458 : clobbered by this call. */
459 :
460 : ulong
461 : fd_vinyl_io_append_pair_inplace( fd_vinyl_io_t * io,
462 : int style,
463 : fd_vinyl_bstream_phdr_t * phdr,
464 : int * _style,
465 : ulong * _val_esz );
466 :
467 : /* fd_vinyl_io_bd *****************************************************/
468 :
469 : /* fd_vinyl_io_bd_{align,footprint} specify the alignment and footprint
470 : needed for a bstream stored on a block device / large file with a
471 : spad_max append scratch pad. align will be a reasonable power-of-2
472 : and footprint will be a multiple of align. Returns 0 for an invalid
473 : spad_max.
474 :
475 : fd_vinyl_io_bd_init starts using a file as a bstream store. lmem
476 : points to a local memory region with suitable alignment and footprint
477 : to hold the bstream's state. spad_max gives the size of the append
478 : scratch pad (should be a FD_VINYL_BSTREAM_BLOCK_SZ multiple). dev_fd
479 : is a file descriptor for the block device / large file. The file
480 : should already exist and be sized to the appropriate capacity.
481 :
482 : FIXME: allow user to specify a subrange of dev_fd to use for the
483 : store?
484 :
485 : If reset is non-zero, ignores any existing file contents and will
486 : start a new bstream. The bstream metadata user info will be set to
487 : the info_sz bytes at info and the bstream will use io_seed for its
488 : data integrity hashing seed.
489 :
490 : Otherwise, this will attempt to resume at the point the bstream was
491 : last synchronized. info, info_sz and io_seed will be ignored.
492 :
493 : IMPORTANT SAFETY TIP! The io_seed is the not same thing as the meta
494 : seed. The io_seed is a property of the bstream (with a lifetime of
495 : the bstream and is shared among all users of the bstream). The meta
496 : seed is a property of the meta (and ideally uniquely and randomly set
497 : per vinyl tile run).
498 :
499 : Returns a handle to the bstream on success (has ownership of lmem and
500 : dev_fd, ownership returned on fini) and NULL on failure (logs
501 : details, no ownership changed). Retains no interest in info. */
502 :
503 : ulong fd_vinyl_io_bd_align ( void );
504 : ulong fd_vinyl_io_bd_footprint( ulong spad_max );
505 :
506 : fd_vinyl_io_t *
507 : fd_vinyl_io_bd_init( void * lmem,
508 : ulong spad_max,
509 : int dev_fd,
510 : int reset,
511 : void const * info,
512 : ulong info_sz,
513 : ulong io_seed );
514 :
515 : /* fd_vinyl_io_mm *****************************************************/
516 :
517 : /* fd_vinyl_io_mm_* is the same as fd_vinyl_io_bd_* but uses dev_sz byte
518 : sized memory region dev as the "block device". The result is
519 : bit-level identical to fd_vinyl_io_bd (and vice versa). This is
520 : primarily for testing purposes but, as dev could also be a memory
521 : mapped file / block device, this could be useful in general
522 : (especially for concurrent read access, e.g. parallel recovery).
523 : Note that "sync" only guarantees appends to the dev memory region
524 : happened. If the memory region is backed by a file, when the actual
525 : blocks are written to the physical storage is controlled by the
526 : kernel / driver / physical device (it is up to the caller of sync to
527 : do any additional context specific control here). */
528 :
529 : ulong fd_vinyl_io_mm_align ( void );
530 : ulong fd_vinyl_io_mm_footprint( ulong spad_max );
531 :
532 : fd_vinyl_io_t *
533 : fd_vinyl_io_mm_init( void * lmem,
534 : ulong spad_max,
535 : void * dev,
536 : ulong dev_sz,
537 : int reset,
538 : void const * info,
539 : ulong info_sz,
540 : ulong io_seed );
541 :
542 : /* fd_vinyl_{mmio,mmio_sz} return {a pointer in the caller's address
543 : space to the raw bstream storage,the raw bstream storage byte size).
544 : These are a _subset_ of the dev / dev_sz region passed to mm_init and
545 : these will be FD_VINYL_BSTREAM_BLOCK_SZ aligned. If a byte seq is in
546 : the store, it will be at mmio[ seq % mmio_sz ]. Note that mmio_sz is
547 : not necessarily a power of two. Note also that the bstream's past is
548 : guaranteed to be in the store. The lifetime of the returned region
549 : is the lifetime of the io. Returns NULL and 0 if io does not support
550 : memory mapped io. These exist to support thread parallel recovery. */
551 :
552 : void * fd_vinyl_mmio ( fd_vinyl_io_t * io );
553 : ulong fd_vinyl_mmio_sz( fd_vinyl_io_t * io );
554 :
555 : FD_PROTOTYPES_END
556 :
557 : #endif /* HEADER_fd_src_vinyl_io_fd_vinyl_io_h */
|
