osl.h.m4

   1 VERBATIM_C(«
   2 /*
   3  * Copyright (C) 2007-2009 Andre Noll <maan@tuebingen.mpg.de>
   4  *
   5  * Licensed under the GPL v2. For licencing details see COPYING.
   6  */
   7
   8 /* User interface for the object storage layer. */
   9
  10 #include <sys/mman.h>
  11 #include <inttypes.h>
  12
  13 /* Export all declarations in this file. */
  14 #pragma GCC visibility push(default)
  15 »)
  16
  17 DECLARE_COMPOUND(
  18         «struct osl_object»,
  19         «Describes an object of the object storage layer.»,
  20         «»,
  21         «
  22                 «void *data», «Pointer to the data of the object.»,
  23                 «size_t size», «The object's size.»
  24         »
  25 )
  26
  27 DECLARE_ENUM(
  28         «osl_table_flags»,
  29         «Flags that change the internal handling of osl tables.»,
  30         «»,
  31         «
  32                 «OSL_LARGE_TABLE = 1»,
  33                 «This table will have many rows.»
  34         »
  35 )
  36
  37 DECLARE_ENUM(
  38         «osl_storage_type»,
  39         «The three different types of storage for an osl column.»,
  40         «»,
  41         «
  42                 «OSL_MAPPED_STORAGE»,
  43                 «All data for this column is stored in one file which gets mmapped
  44                 by osl_open_table(). This is suitable for columns that do not hold
  45                 much data.»,
  46
  47                 «OSL_DISK_STORAGE»,
  48                 «Each entry is stored on disk and is loaded on demand by
  49                 open_disk_object(). This is the preferable storage type for large
  50                 objects that need not be in memory all the time.»,
  51
  52                 «OSL_NO_STORAGE»,
  53                 «Objects for columns of this type are volatile: They are only stored
  54                 in memory and are discarded when the table is closed.»
  55         »
  56 )
  57
  58 DECLARE_ENUM(
  59         «osl_storage_flags»,
  60         «Additional per-column flags.»,
  61         «»,
  62         «
  63                 «OSL_RBTREE = 1»,
  64                 «Build an rbtree for this column. This is only possible if the storage
  65                 type of the column is either OSL_MAPPED_STORAGE or OSL_NO_STORAGE. In
  66                 order to lookup objects in the table by using osl_get_row(), the
  67                 lookup column must have an associated rbtree.
  68
  69                 See also: osl_storage_type, osl_get_row()»,
  70
  71                 «OSL_FIXED_SIZE = 2»,
  72                 «The data for this column will have constant size.»,
  73
  74                 «OSL_UNIQUE = 4»,
  75                 «All values are different. Must be set if OSL_RBTREE is set.»,
  76
  77                 «OSL_DONT_FREE = 8»,
  78                 «Do not free the data for this column (OSL_NO_STORAGE).»
  79         »
  80 )
  81
  82 STATEMENT(
  83         «struct osl_table»,
  84         «Opaque osl table structure.»
  85 )
  86
  87 STATEMENT(
  88         «struct osl_row»,
  89         «Opaque osl row structure.»
  90 )
  91
  92 STATEMENT(
  93         «typedef int osl_compare_func(const struct osl_object *obj1, const struct osl_object *obj2)»,
  94         «Comparator for rbtree nodes.»,
  95         «To build an rbtree, a compare function for the objects must be
  96         provided. This function takes pointers to the two objects to be
  97         compared. It must return -1, zero, or 1, if the first argument is
  98         considered to be respectively less than, equal to, or greater than
  99         the second. If two members compare as equal, their order in the rbtree
 100         is undefined.»
 101 )
 102
 103 STATEMENT(
 104         «typedef int osl_rbtree_loop_func(struct osl_row *row, void *data)»,
 105         «Loop callback function.»,
 106         «The osl_rbreee_loop functions take a function pointer of this
 107         type. For each node in the rbtree, the given function is called.
 108
 109         See also: osl_rbtree_loop(), osl_rbtree_loop_reverse().»
 110 )
 111
 112 DECLARE_COMPOUND(
 113         «struct osl_column_description»,
 114         «Describes one column of an osl table.»,
 115         «», «
 116                 «uint16_t storage_type»,
 117                 «One of the three possible types of storage. See also:
 118                 osl_storage_type.»,
 119
 120                 «uint16_t storage_flags»,
 121                 «Specifies further properties of the column. See also:
 122                 osl_storage_flags.»,
 123
 124                 «char *name»,
 125                 «The column name determines the name of the directory where all
 126                 data for this column will be stored. Its hash is stored in the table
 127                 header. This field is ignored if the storage type is NO_STORAGE.»,
 128
 129                 «osl_compare_func *compare_function»,
 130                 «For columns with an associated rbtree, this must point to a function
 131                 that compares the values of two objects, either a built-in function
 132                 or a function defined by the application may be supplied. This field
 133                 is ignored if the column does not have an associated rbtree.
 134
 135                 See also: osl_storage_flags, osl_compare_func»,
 136
 137                 «uint32_t data_size»,
 138                 «If the OSL_FIXED_SIZE flag is set for this column, this value
 139                 describes the number of bytes of each object of this column. It is
 140                 ignored, if OSL_FIXED_SIZE is not set.»
 141         »
 142 )
 143
 144 DECLARE_COMPOUND(
 145         «struct osl_table_description»,
 146         «Describes one osl table.»,
 147         «A pointer to the table description is passed to osl_create_table()
 148         and osl_open_table(). The osl library calls which operate on an
 149         open table refer to the fields of the table description through this
 150         pointer. Hence the table description must not be modified or freed
 151         before the table is closed.»,
 152
 153         «
 154                 «const char *dir»,
 155                 «The directory which contains all files of this table. This may be
 156                 either relative to the cwd or an absolute path.»,
 157
 158                 «const char *name»,
 159                 «The table name. A subdirectory of dir called name is created at
 160                 table creation time. It must be a valid name for a subdirectory.
 161                 In particular, no slashes are allowed in the name.»,
 162
 163                 «uint16_t num_columns»,
 164                 «The number of columns of this table.»,
 165
 166                 «uint8_t flags»,
 167                 «Further table-wide information, see osl_table_flags.»,
 168
 169                 «struct osl_column_description *column_descriptions»,
 170                 «The array describing the individual columns of the table.»
 171         »
 172 )
 173
 174 DECLARE_ENUM(
 175         «osl_close_flags»,
 176         «Flags to be passed to osl_close_table().»,
 177         «»,
 178         «
 179                 «OSL_MARK_CLEAN = 1»,
 180                 «The table header contains a "dirty" flag which indicates whether the
 181                 table is currently held open by another process. The OSL_MARK_CLEAN
 182                 flag instructs libosl to clear the dirty flag when the table is
 183                 closed.»,
 184
 185                 «OSL_FREE_VOLATILE = 2»,
 186                 «If the table contains columns of type OSL_NO_STORAGE and this flag
 187                 is passed to osl_close_table(), free(3) is called for each object of
 188                 each column of type OSL_NO_STORAGE.»
 189         »
 190 )
 191
 192 DECLARE_FUNCTION(
 193         «osl_create_table»,
 194         «Create a new osl table.»,
 195         «»,
 196         «
 197                 «const struct osl_table_description *desc»,
 198                 «Pointer to the table description»
 199         »,
 200         «»,
 201         «int»,
 202         «Standard»
 203 )
 204
 205 DECLARE_FUNCTION(
 206         «osl_open_table»,
 207         «Open an osl table.»,
 208         «An osl table must be opened before its data can be accessed.»,
 209         «
 210                 «const struct osl_table_description *desc»,
 211                 «Describes the table to be opened»,
 212
 213                 «struct osl_table **result»,
 214                 «Contains a pointer to the open table on success.»
 215         »,
 216         «The table description given by desc should coincide with the
 217         description used at creation time.»,
 218
 219         «int»,
 220         «Standard»
 221 )
 222
 223 DECLARE_FUNCTION(
 224         «osl_close_table»,
 225         «Close an osl table.»,
 226         «»,
 227         «
 228                 «struct osl_table *t»,
 229                 «Pointer to the table to be closed.»,
 230
 231                 «enum osl_close_flags flags»,
 232                 «Options for what should be cleaned up.»
 233         »,
 234         «If osl_open_table() succeeds, the resulting table pointer must
 235         later be passed to this function in order to flush all changes to
 236         the file system and to free the resources that were allocated by
 237         osl_open_table().»,
 238
 239         «int»,
 240         «Standard»
 241 )
 242
 243 DECLARE_FUNCTION(
 244         «osl_get_row»,
 245         «Get the row that contains the given object.»,
 246         «»,
 247         «
 248                 «const struct osl_table *t»,
 249                 «Pointer to an open osl table»,
 250
 251                 «unsigned col_num»,
 252                 «The number of the column to be searched»,
 253
 254                 «const struct osl_object *obj»,
 255                 «The object to be looked up»,
 256
 257                 «struct osl_row **result»,
 258                 «Points to the row containing the given object»
 259         »,
 260         «Lookup the given object and return the row containing it. The column
 261         specified by col_num must have an associated rbtree.»,
 262
 263         «int»,
 264         «Standard. The result pointer is set to NULL if and only if the
 265         function returns negative.»
 266 )
 267
 268 DECLARE_FUNCTION(
 269         «osl_get_object»,
 270         «Retrieve an object identified by row and column.»,
 271         «»,
 272         «
 273                 «const struct osl_table *t»,
 274                 «Pointer to an open osl table»,
 275
 276                 «const struct osl_row *row»,
 277                 «Pointer to the row»,
 278
 279                 «unsigned col_num»,
 280                 «The column number»,
 281
 282                 «struct osl_object *object»,
 283                 «The result pointer»
 284         »,
 285         «The column determined by col_num must be of type OSL_MAPPED_STORAGE
 286         or OSL_NO_STORAGE, i.e. no disk storage objects may be retrieved by
 287         this function.
 288
 289         See also: osl_storage_type, osl_open_disk_object().»,
 290         «int»,
 291         «Standard»
 292 )
 293
 294 DECLARE_FUNCTION(
 295         «osl_open_disk_object»,
 296         «Retrieve an object of type OSL_DISK_STORAGE by row and column.»,
 297         «For columns of type OSL_DISK_STORAGE this function must be
 298         used to retrieve one of its containing objects. Afterwards,
 299         osl_close_disk_object() must be called in order to deallocate the
 300         resources.»,
 301
 302         «
 303                 «const struct osl_table *t»,
 304                 «Pointer to an open osl table»,
 305
 306                 «const struct osl_row *r»,
 307                 «Pointer to the row containing the object»,
 308
 309                 «unsigned col_num»,
 310                 «The column number»,
 311
 312                 «struct osl_object *obj»,
 313                 «Points to the result upon successful return»
 314         »,
 315         «See also: osl_get_object(), osl_storage_type,
 316         osl_close_disk_object().»,
 317
 318         «int»,
 319         «Standard»
 320 )
 321
 322 DECLARE_FUNCTION(
 323         «osl_close_disk_object»,
 324         «Free resources allocated during osl_open_disk_object().», «
 325         », «
 326                 «struct osl_object *obj»,
 327                 «Pointer to the object previously returned by open_disk_object()»
 328         »,
 329         «»,
 330         «int», «The return value of the underlying call to munmap(2)»
 331 )
 332
 333 DECLARE_FUNCTION(
 334         «osl_add_and_get_row»,
 335         «Add a new row to an osl table and retrieve this row.»,
 336         «»,
 337         «
 338                 «struct osl_table *t»,
 339                 «Pointer to an open osl table»,
 340
 341                 «struct osl_object *objects»,
 342                 «Array of objects to be added»,
 343
 344                 «struct osl_row **row»,
 345                 «Result pointer»
 346         »,
 347         «The objects parameter must point to an array containing one object
 348         per column. The order of the objects in the array is given by the
 349         table description of the table. Several sanity checks are performed
 350         during object insertion and the function returns without modifying the
 351         table if any of these tests fail. In fact, it is atomic in the sense
 352         that it either succeeds or leaves the table unchanged (i.e. either
 353         all or none of the objects are added to the table).
 354
 355         See also: struct osl_table_description, osl_compare_func,
 356         osl_add_row().»,
 357
 358         «int»,
 359         «Standard»
 360 )
 361
 362 DECLARE_FUNCTION(
 363         «osl_add_row»,
 364         «Add a new row to an osl table.»,
 365         «»,
 366         «
 367                 «struct osl_table *t»,
 368                 «Same meaning as osl_add_and_get_row()»,
 369
 370                 «struct osl_object *objects»,
 371                 «Same meaning as osl_add_and_get_row()»
 372         »,
 373         «This is equivalent to calling osl_add_and_get_row(t, objects,
 374         NULL);»,
 375
 376         «int»,
 377         «The return value of the underlying call to osl_add_and_get_row()»
 378 )
 379
 380 DECLARE_FUNCTION(
 381         «osl_del_row»,
 382         «Delete a row from an osl table.»,
 383         «»,
 384         «
 385                 «struct osl_table *t»,
 386                 «Pointer to an open osl table»,
 387
 388                 «struct osl_row *row»,
 389                 «Pointer to the row to delete»
 390         »,
 391         «This removes all disk storage objects, removes all rbtree nodes,
 392         and frees all volatile objects belonging to the given row. For mapped
 393         columns, the data is merely marked invalid and may be pruned from
 394         time to time by oslfsck(1).»,
 395
 396         «int»,
 397         «Standard»
 398 )
 399
 400 DECLARE_FUNCTION(
 401         «osl_rbtree_loop»,
 402         «Loop over all nodes in an rbtree.»,
 403         «»,
 404         «
 405                 «const struct osl_table *t»,
 406                 «Pointer to an open osl table»,
 407
 408                 «unsigned col_num»,
 409                 «The column to use for iterating over the elements»,
 410
 411                 «void *private_data»,
 412                 «Pointer that gets passed to the callback function»,
 413
 414                 «osl_rbtree_loop_func *func»,
 415                 «This callback is called for each node in the rbtree.»
 416         »,
 417         «This function does an in-order walk of the rbtree associated with
 418         col_num. It is an error if the OSL_RBTREE flag is not set for this
 419         column. For each node in the rbtree, the given function func is called
 420         with two pointers as arguments: The first osl_row* argument points
 421         to the row that contains the object corresponding to the rbtree node
 422         currently traversed, and the private_data pointer is passed verbatim as
 423         the second argument. The loop terminates either if the callback returns
 424         a negative value, or if all nodes of the tree have been visited.»,
 425
 426         «int»,
 427         «Standard. If the termination of the loop was caused by the callback
 428         returning a negative value, -E_OSL_LOOP is returned. This is the only
 429         possible error.»
 430 )
 431
 432 DECLARE_FUNCTION(
 433         «osl_rbtree_loop_reverse»,
 434         «Loop over all nodes in an rbtree in reverse order.»,
 435         «This function is identical to osl_rbtree_loop(), the only difference
 436         is that the tree is walked in reverse order.»,
 437         «
 438                 «const struct osl_table *t»,
 439                 «See osl_rbtree_loop()»,
 440
 441                 «unsigned col_num»,
 442                 «See osl_rbtree_loop()»,
 443
 444                 «void *private_data»,
 445                 «See osl_rbtree_loop()»,
 446
 447                 «osl_rbtree_loop_func *func»,
 448                 «See osl_rbtree_loop()»
 449         »,
 450         «See also: osl_rbtree_loop().»,
 451         «int»,
 452         «The same return value as osl_rbtree_loop()»
 453 )
 454
 455 DECLARE_FUNCTION(
 456         «osl_update_object»,
 457         «Change an object of an osl table.»,
 458         «»,
 459         «
 460                 «struct osl_table *t»,
 461                 «Pointer to an open osl table»,
 462
 463                 «const struct osl_row *r»,
 464                 «Pointer to the row containing the object to be updated»,
 465
 466                 «unsigned col_num»,
 467                 «Number of the column containing the object to be updated»,
 468
 469                 «struct osl_object *obj»,
 470                 «Pointer to the replacement object»
 471         »,
 472         «This function gets rid of all references to the old object. This
 473         includes removal of the rbtree node in case there is an rbtree
 474         associated with col_num. It then inserts obj into the table and the
 475         rbtree if necessary.»,
 476
 477         «int»,
 478         «Standard»
 479 )
 480
 481 DECLARE_FUNCTION(
 482         «osl_get_num_rows»,
 483         «Get the number of rows of the given table.»,
 484         «»,
 485         «
 486                 «const struct osl_table *t»,
 487                 «Pointer to an open osl table»,
 488
 489                 «unsigned *num_rows»,
 490                 «Result is returned here»
 491         »,
 492         «The number of rows returned excludes any invalid rows.»,
 493
 494         «int»,
 495         «Positive on success, -E_OSL_BAD_TABLE if t is NULL»
 496 )
 497
 498 DECLARE_FUNCTION(
 499         «osl_rbtree_first_row»,
 500         «Get the row corresponding to the smallest rbtree node of a column.»,
 501         «»,
 502         «
 503                 «const struct osl_table *t»,
 504                 «An open table»,
 505
 506                 «unsigned col_num»,
 507                 «The number of the rbtree column»,
 508
 509                 «struct osl_row **result»,
 510                 «A pointer to the first row is returned here»
 511         »,
 512         «The rbtree node of the smallest object (with respect to the
 513         corresponding compare function) is selected and the row containing
 514         this object is returned. It is an error if col_num refers to a column
 515         without an associated rbtree.
 516
 517         See also: osl_get_nth_row(), osl_rbtree_last_row().»,
 518         «int»,
 519         «Standard»
 520 )
 521
 522 DECLARE_FUNCTION(
 523         «osl_rbtree_last_row»,
 524         «Get the row corresponding to the greatest rbtree node of a column.»,
 525         «This function works just like osl_rbtree_first_row(), the only
 526         difference is that the row containing the greatest rather than the
 527         smallest object is returned.»,
 528
 529         «
 530                 «const struct osl_table *t»,
 531                 «See osl_rbtree_first_row()»,
 532
 533                 «unsigned col_num»,
 534                 «See osl_rbtree_first_row()»,
 535
 536                 «struct osl_row **result»,
 537                 «See osl_rbtree_first_row()»
 538         »,
 539         «See also: osl_get_nth_row(), osl_rbtree_first_row()»,
 540         «int»,
 541         «Standard»
 542 )
 543
 544 DECLARE_FUNCTION(
 545         «osl_get_nth_row»,
 546         «Get the row with n-th greatest value.»,
 547         «»,
 548         «
 549                 «const struct osl_table *t»,
 550                 «Pointer to an open osl table»,
 551
 552                 «unsigned col_num»,
 553                 «The column number»,
 554
 555                 «unsigned n»,
 556                 «The rank of the desired row»,
 557
 558                 «struct osl_row **result»,
 559                 «Row is returned here»
 560         »,
 561         «Retrieve the n-th order statistic with respect to the compare
 562         function of the rbtree column col_num. In other words, get the row
 563         with n-th greatest value in column col_num. It is an error if col_num
 564         is not a rbtree column, or if n is larger than the number of rows in
 565         the table.»,
 566
 567         «int»,
 568         «Standard»
 569 )
 570
 571 DECLARE_FUNCTION(
 572         «osl_get_rank»,
 573         «Get the rank of a row.»,
 574         «The rank is, by definition, the position of the row in the linear
 575         order determined by an in-order tree walk of the rbtree associated
 576         with given column number.»,
 577
 578         «
 579                 «const struct osl_table *t»,
 580                 «An open osl table»,
 581
 582                 «struct osl_row *r»,
 583                 «The row to get the rank of»,
 584
 585                 «unsigned col_num»,
 586                 «The number of an rbtree column»,
 587
 588                 «unsigned *rank»,
 589                 «Result pointer»
 590         »,
 591         «See also: osl_get_nth_row().»,
 592         «int»,
 593         «Standard»
 594 )
 595
 596 DECLARE_FUNCTION(
 597         «osl_strerror»,
 598         «Get a string describing the error code passed in the argument.»,
 599         «»,
 600         «
 601                 «int num»,
 602                 «The error code»
 603         »,
 604         «This works just like strerror(3). The given number must be an osl
 605         error code. The result must not be freed by the caller.»,
 606
 607         «const char *»,
 608         «The error text corresponding to an osl error code»
 609 )
 610
 611 VERBATIM_C(«
 612 #pragma GCC visibility pop
 613 »)