summaryrefslogtreecommitdiffstats
path: root/src/include/radosstriper/libradosstriper.h
blob: a35345f7d185a4fb69195f0aa63814a7968a6a7e (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
#ifndef CEPH_LIBRADOSSTRIPER_H
#define CEPH_LIBRADOSSTRIPER_H

#ifdef __cplusplus
extern "C" {
#endif

#include <string.h>

#include "../rados/librados.h"

#define LIBRADOSSTRIPER_VER_MAJOR 0
#define LIBRADOSSTRIPER_VER_MINOR 0
#define LIBRADOSSTRIPER_VER_EXTRA 0

#define LIBRADOSSTRIPER_VERSION(maj, min, extra) ((maj << 16) + (min << 8) + extra)

#define LIBRADOSSTRIPER_VERSION_CODE LIBRADOSSTRIPER_VERSION(LIBRADOSSTRIPER_VER_MAJOR, LIBRADOSSTRIPER_VER_MINOR, LIBRADOSSTRIPER_VER_EXTRA)

/**
 * @typedef rados_striper_t
 *
 * A handle for interacting with striped objects in a RADOS cluster.
 */
typedef void *rados_striper_t;

/**
 * @defgroup libradosstriper_h_init Setup and Teardown
 * These are the first and last functions to that should be called
 * when using libradosstriper.
 *
 * @{
 */

/**
 * Creates a rados striper using the given io context
 * Striper has initially default object layout.
 * See rados_striper_set_object_layout_*() to change this
 *
 * @param ioctx the rados context to use
 * @param striper where to store the rados striper
 * @returns 0 on success, negative error code on failure
 */
  int rados_striper_create(rados_ioctx_t ioctx,
                           rados_striper_t *striper);

/**
 * Destroys a rados striper
 *
 * @param striper the striper to destroy
 */
void rados_striper_destroy(rados_striper_t striper);

/**
 * Sets the object layout's stripe unit of a rados striper for future objects.
 * This layout will be used when new objects are created (by writing to them)
 * Already existing objects will be opened with their own layout.
 *
 * @param striper the targeted striper
 * @param stripe_unit the stripe_unit value of the new object layout
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_set_object_layout_stripe_unit(rados_striper_t striper,
                                                unsigned int stripe_unit);

/**
 * Sets the object layout's stripe count of a rados striper for future objects.
 * This layout will be used when new objects are created (by writing to them)
 * Already existing objects will be opened with their own layout.
 *
 * @param striper the targeted striper
 * @param stripe_count the stripe_count value of the new object layout
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_set_object_layout_stripe_count(rados_striper_t striper,
                                                 unsigned int stripe_count);

/**
 * Sets the object layout's object_size of a rados striper for future objects.
 * This layout will be used when new objects are created (by writing to them)
 * Already existing objects will be opened with their own layout.
 *
 * @param striper the targeted striper
 * @param object_size the object_size value of the new object layout
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_set_object_layout_object_size(rados_striper_t striper,
                                                unsigned int object_size);

/** @} init */

/**
 * @defgroup libradosstriper_h_synch_io Synchronous I/O
 * Writes are striped to several rados objects which are then
 * replicated to a number of OSDs based on the configuration
 * of the pool they are in. These write functions block
 * until data is in memory on all replicas of the object they're
 * writing to - they are equivalent to doing the corresponding
 * asynchronous write, and the calling
 * rados_striper_ioctx_wait_for_complete().
 *
 * @{
 */

/**
 * Synchronously write data to a striped object at the specified offset
 *
 * @param striper the striper in which the write will occur
 * @param soid the name of the striped object
 * @param buf data to write
 * @param len length of the data, in bytes
 * @param off byte offset in the object to begin writing at
 * @returns 0 on success, negative error code on failure
 * failure
 */
int rados_striper_write(rados_striper_t striper,
                        const char *soid,
                        const char *buf,
                        size_t len,
                        uint64_t off);

/**
 * Synchronously write an entire striped object
 *
 * The striped object is filled with the provided data. If the striped object exists,
 * it is truncated and then written.
 *
 * @param striper the striper in which the write will occur
 * @param soid the name of the striped object
 * @param buf data to write
 * @param len length of the data, in bytes
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_write_full(rados_striper_t striper,
                             const char *soid,
                             const char *buf,
                             size_t len);

/**
 * Append data to an object
 *
 * @param striper the striper in which the write will occur
 * @param soid the name of the striped object
 * @param buf the data to append
 * @param len length of buf (in bytes)
 * @returns 0 on success, negative error code on failure
 * failure
 */
int rados_striper_append(rados_striper_t striper,
                         const char *soid,
                         const char *buf,
                         size_t len);

/**
 * Synchronously read data from a striped object at the specified offset
 *
 * @param striper the striper in which the read will occur
 * @param soid the name of the striped object
 * @param buf where to store the results
 * @param len the number of bytes to read
 * @param off the offset to start reading from in the object
 * @returns number of bytes read on success, negative error code on
 * failure
 */
int rados_striper_read(rados_striper_t striper,
                       const char *soid,
                       char *buf,
                       size_t len,
                       uint64_t off);

/**
 * Synchronously removes a striped object
 *
 * @note There is no atomicity of the deletion and the striped
 * object may be left incomplete if an error is returned (metadata
 * all present, but some stripes missing)
 * However, there is a atomicity of the metadata deletion and
 * the deletion can not happen if any I/O is ongoing (it
 * will return EBUSY). Identically, no I/O will be able to start
 * during deletion (same EBUSY return code)
 * @param striper the striper in which the remove will occur
 * @param soid the name of the striped object
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_remove(rados_striper_t striper,
                         const char* soid);

/**
 * Resize an object
 *
 * If this enlarges the object, the new area is logically filled with
 * zeroes. If this shrinks the object, the excess data is removed.
 *
 * @note the truncation is not fully atomic. The metadata part is,
 * so the behavior will be atomic from user point of view when
 * the object size is reduced. However, in case of failure, old data
 * may stay around, hidden. They may reappear if the object size is
 * later grown, instead of the expected 0s. When growing the
 * object and in case of failure, the new 0 data may not be
 * fully created. This can lead to ENOENT errors when
 * writing/reading the missing parts.
 * @note the truncation can not happen if any I/O is ongoing (it
 * will return EBUSY). Identically, no I/O will be able to start
 * during truncation (same EBUSY return code)
 * @param io the rados context to use
 * @param soid the name of the striped object
 * @param size the new size of the object in bytes
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_trunc(rados_striper_t striper, const char *soid, uint64_t size);

/** @} Synchronous I/O */

/**
 * @defgroup libradosstriper_h_xattrs Xattrs
 * Extended attributes are stored as extended attributes on the
 * first rados regular object of the striped object.
 * Thus, they have the same limitations as the underlying
 * rados extended attributes.
 *
 * @{
 */

/**
 * Get the value of an extended attribute on a striped object.
 *
 * @param striper the striper in which the getxattr will occur
 * @param oid name of the striped object
 * @param name which extended attribute to read
 * @param buf where to store the result
 * @param len size of buf in bytes
 * @returns length of xattr value on success, negative error code on failure
 */
int rados_striper_getxattr(rados_striper_t striper,
                           const char *oid,
                           const char *name,
                           char *buf,
                           size_t len);

/**
 * Set an extended attribute on a striped object.
 *
 * @param striper the striper in which the setxattr will occur
 * @param oid name of the object
 * @param name which extended attribute to set
 * @param buf what to store in the xattr
 * @param len the number of bytes in buf
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_setxattr(rados_striper_t striper,
                           const char *oid,
                           const char *name,
                           const char *buf,
                           size_t len);

/**
 * Delete an extended attribute from a striped object.
 *
 * @param striper the striper in which the rmxattr will occur
 * @param oid name of the object
 * @param name which xattr to delete
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_rmxattr(rados_striper_t striper,
                          const char *oid,
                          const char *name);

/**
 * Start iterating over xattrs on a striped object.
 *
 * @post iter is a valid iterator
 *
 * @param striper the striper in which the getxattrs will occur
 * @param oid name of the object
 * @param iter where to store the iterator
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_getxattrs(rados_striper_t striper,
                            const char *oid,
                            rados_xattrs_iter_t *iter);

/**
 * Get the next xattr on the striped object
 *
 * @pre iter is a valid iterator
 *
 * @post name is the NULL-terminated name of the next xattr, and val
 * contains the value of the xattr, which is of length len. If the end
 * of the list has been reached, name and val are NULL, and len is 0.
 *
 * @param iter iterator to advance
 * @param name where to store the name of the next xattr
 * @param val where to store the value of the next xattr
 * @param len the number of bytes in val
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_getxattrs_next(rados_xattrs_iter_t iter,
                                 const char **name,
                                 const char **val,
                                 size_t *len);

/**
 * Close the xattr iterator.
 *
 * iter should not be used after this is called.
 *
 * @param iter the iterator to close
 */
void rados_striper_getxattrs_end(rados_xattrs_iter_t iter);

/** @} Xattrs */

/**
 * Synchronously get object stats (size/mtime)
 *
 * @param striper the striper in which the stat will occur
 * @param soid the id of the striped object
 * @param psize where to store object size
 * @param pmtime where to store modification time
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_stat(rados_striper_t striper,
                       const char* soid,
                       uint64_t *psize,
                       time_t *pmtime);

int rados_striper_stat2(rados_striper_t striper,
                       const char* soid,
                       uint64_t *psize,
                       struct timespec *pmtime);

/**
 * @defgroup libradosstriper_h_asynch_io Asynchronous I/O
 * Read and write to objects without blocking.
 *
 * @{
 */

/**
 * @typedef rados_striper_multi_completion_t
 * Represents the state of a set of asynchronous operations
 * it contains the aggregated return value once the operations complete
 * and can be used to block until all operations are complete and/or safe.
 */
typedef void *rados_striper_multi_completion_t;

/**
 * Constructs a multi completion to use with asynchronous operations
 *
 * The complete and safe callbacks correspond to operations being
 * acked and committed, respectively. The callbacks are called in
 * order of receipt, so the safe callback may be triggered before the
 * complete callback, and vice versa. This is affected by journalling
 * on the OSDs.
 *
 * @note Read operations only get a complete callback.
 * @note BUG: this should check for ENOMEM instead of throwing an exception
 *
 * @param cb_arg application-defined data passed to the callback functions
 * @param cb_complete the function to be called when the operation is
 * in memory on all relpicas
 * @param cb_safe the function to be called when the operation is on
 * stable storage on all replicas
 * @param pc where to store the completion
 * @returns 0
 */
int rados_striper_multi_aio_create_completion(void *cb_arg,
                                              rados_callback_t cb_complete,
                                              rados_callback_t cb_safe,
                                              rados_striper_multi_completion_t *pc);

/**
 * Block until all operation complete
 *
 * This means data is in memory on all replicas.
 *
 * @param c operations to wait for
 * @returns 0
 */
void rados_striper_multi_aio_wait_for_complete(rados_striper_multi_completion_t c);

/**
 * Block until all operation are safe
 *
 * This means data is on stable storage on all replicas.
 *
 * @param c operations to wait for
 * @returns 0
 */
void rados_striper_multi_aio_wait_for_safe(rados_striper_multi_completion_t c);

/**
 * Has a multi asynchronous operation completed?
 *
 * @warning This does not imply that the complete callback has
 * finished
 *
 * @param c async operations to inspect
 * @returns whether c is complete
 */
int rados_striper_multi_aio_is_complete(rados_striper_multi_completion_t c);

/**
 * Is a multi asynchronous operation safe?
 *
 * @warning This does not imply that the safe callback has
 * finished
 *
 * @param c async operations to inspect
 * @returns whether c is safe
 */
int rados_striper_multi_aio_is_safe(rados_striper_multi_completion_t c);

/**
 * Block until all operations complete and callback completes
 *
 * This means data is in memory on all replicas and can be read.
 *
 * @param c operations to wait for
 * @returns 0
 */
void rados_striper_multi_aio_wait_for_complete_and_cb(rados_striper_multi_completion_t c);

/**
 * Block until all operations are safe and callback has completed
 *
 * This means data is on stable storage on all replicas.
 *
 * @param c operations to wait for
 * @returns 0
 */
void rados_striper_multi_aio_wait_for_safe_and_cb(rados_striper_multi_completion_t c);

/**
 * Has a multi asynchronous operation and callback completed
 *
 * @param c async operations to inspect
 * @returns whether c is complete
 */
int rados_striper_multi_aio_is_complete_and_cb(rados_striper_multi_completion_t c);

/**
 * Is a multi asynchronous operation safe and has the callback completed
 *
 * @param c async operations to inspect
 * @returns whether c is safe
 */
int rados_striper_multi_aio_is_safe_and_cb(rados_striper_multi_completion_t c);

/**
 * Get the return value of a multi asychronous operation
 *
 * The return value is set when all operations are complete or safe,
 * whichever comes first.
 *
 * @pre The operation is safe or complete
 *
 * @note BUG: complete callback may never be called when the safe
 * message is received before the complete message
 *
 * @param c async operations to inspect
 * @returns aggregated return value of the operations
 */
int rados_striper_multi_aio_get_return_value(rados_striper_multi_completion_t c);

/**
 * Release a multi asynchrnous IO completion
 *
 * Call this when you no longer need the completion. It may not be
 * freed immediately if the operation is not acked and committed.
 *
 * @param c multi completion to release
 */
void rados_striper_multi_aio_release(rados_striper_multi_completion_t c);

/**
 * Asynchronously write data to a striped object at the specified offset
 *
 * The return value of the completion will be 0 on success, negative
 * error code on failure.
 *
 * @param striper the striper in which the write will occur
 * @param soid the name of the striped object
 * @param completion what to do when the write is safe and complete
 * @param buf data to write
 * @param len length of the data, in bytes
 * @param off byte offset in the object to begin writing at
 * @returns 0 on success, negative error code on
 * failure
 */
int rados_striper_aio_write(rados_striper_t striper,
                            const char *soid,
                            rados_completion_t completion,
                            const char *buf,
                            size_t len,
                            uint64_t off);

/**
 * Asynchronously appends data to a striped object
 *
 * The return value of the completion will be 0 on success, negative
 * error code on failure.
 *
 * @param striper the striper in which the write will occur
 * @param soid the name of the striped object
 * @param completion what to do when the write is safe and complete
 * @param buf data to write
 * @param len length of the data, in bytes
 * @returns 0 on success, negative error code on
 * failure
 */
int rados_striper_aio_append(rados_striper_t striper,
                             const char *soid,
                             rados_completion_t completion,
                             const char *buf,
                             size_t len);

/**
 * Asynchronously fills and object with the provided data.
 * If the object exists, it is truncated and then written.
 *
 * The return value of the completion will be 0 on success, negative
 * error code on failure.
 *
 * @param striper the striper in which the write will occur
 * @param soid the name of the striped object
 * @param completion what to do when the write is safe and complete
 * @param buf data to write
 * @param len length of the data, in bytes
 * @returns 0 on success, negative error code on
 * failure
 */
int rados_striper_aio_write_full(rados_striper_t striper,
                                 const char *soid,
                                 rados_completion_t completion,
                                 const char *buf,
                                 size_t len);

/**
 * Asynchronously read data from a striped object at the specified offset
 *
 * The return value of the completion will be number of bytes read on
 * success, negative error code on failure.
 *
 * @param striper the striper in which the read will occur
 * @param soid the name of the striped object
 * @param completion what to do when the read is safe and complete
 * @param buf where to store the results
 * @param len the number of bytes to read
 * @param off the offset to start reading from in the object
 * @returns 0 on success, negative error code on
 * failure
 */
int rados_striper_aio_read(rados_striper_t striper,
                           const char *soid,
                           rados_completion_t completion,
                           char *buf,
                           const size_t len,
                           uint64_t off);

/**
 * Asynchronously removes a striped object
 *
 * @note There is no atomicity of the deletion and the striped
 * object may be left incomplete if an error is returned (metadata
 * all present, but some stripes missing)
 * However, there is a atomicity of the metadata deletion and
 * the deletion can not happen if any I/O is ongoing (it
 * will return EBUSY). Identically, no I/O will be able to start
 * during deletion (same EBUSY return code)
 * @param striper the striper in which the remove will occur
 * @param soid the name of the striped object
 * @param completion what to do when the remove is safe and complete
 * @returns 0 on success, negative error code on failure
 */

int rados_striper_aio_remove(rados_striper_t striper,
                             const char* soid,
                             rados_completion_t completion);

/**
 * Block until all pending writes in a striper are safe
 *
 * This is not equivalent to calling rados_striper_multi_aio_wait_for_safe() on all
 * write completions, since this waits for the associated callbacks to
 * complete as well.
 *
 * @param striper the striper in which the flush will occur
 * @returns 0 on success, negative error code on failure
*/
void rados_striper_aio_flush(rados_striper_t striper);

/**
 * Asynchronously get object stats (size/mtime)
 *
 * @param striper the striper in which the stat will occur
 * @param soid the id of the striped object
 * @param psize where to store object size
 * @param pmtime where to store modification time
 * @param completion what to do when the stats is complete
 * @returns 0 on success, negative error code on failure
 */
int rados_striper_aio_stat(rados_striper_t striper,
                           const char* soid,
                           rados_completion_t completion,
                           uint64_t *psize,
                           time_t *pmtime);

int rados_striper_aio_stat2(rados_striper_t striper,
                           const char* soid,
                           rados_completion_t completion,
                           uint64_t *psize,
                           struct timespec *pmtime);
/** @} Asynchronous I/O */

#ifdef __cplusplus
}
#endif

#endif