lustre/include/lu_object.h

   1 /* -*- mode: c; c-basic-offset: 8; indent-tabs-mode: nil; -*-
   2  * vim:expandtab:shiftwidth=8:tabstop=8:
   3  *
   4  *  Copyright (C) 2006 Cluster File Systems, Inc.
   5  *
   6  *   This file is part of Lustre, http://www.lustre.org.
   7  *
   8  *   Lustre is free software; you can redistribute it and/or
   9  *   modify it under the terms of version 2 of the GNU General Public
  10  *   License as published by the Free Software Foundation.
  11  *
  12  *   Lustre is distributed in the hope that it will be useful,
  13  *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  *   GNU General Public License for more details.
  16  *
  17  *   You should have received a copy of the GNU General Public License
  18  *   along with Lustre; if not, write to the Free Software
  19  *   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  20  *
  21  */
  22
  23 #ifndef __LUSTRE_LU_OBJECT_H
  24 #define __LUSTRE_LU_OBJECT_H
  25
  26 /*
  27  * struct lu_fid
  28  */
  29 #include <lustre/lustre_idl.h>
  30
  31 #include <libcfs/list.h>
  32 #include <libcfs/kp30.h>
  33
  34 /*
  35  * Layered objects support for CMD3/C5.
  36  */
  37
  38
  39 struct seq_file;
  40 struct proc_dir_entry;
  41 struct lustre_cfg;
  42
  43 /*
  44  * lu_* data-types represent server-side entities shared by data and meta-data
  45  * stacks.
  46  *
  47  * Design goals:
  48  *
  49  * 0. support for layering.
  50  *
  51  *     Server side object is split into layers, one per device in the
  52  *     corresponding device stack. Individual layer is represented by struct
  53  *     lu_object. Compound layered object --- by struct lu_object_header. Most
  54  *     interface functions take lu_object as an argument and operate on the
  55  *     whole compound object. This decision was made due to the following
  56  *     reasons:
  57  *
  58  *        - it's envisaged that lu_object will be used much more often than
  59  *        lu_object_header;
  60  *
  61  *        - we want lower (non-top) layers to be able to initiate operations
  62  *        on the whole object.
  63  *
  64  *     Generic code supports layering more complex than simple stacking, e.g.,
  65  *     it is possible that at some layer object "spawns" multiple sub-objects
  66  *     on the lower layer.
  67  *
  68  * 1. fid-based identification.
  69  *
  70  *     Compound object is uniquely identified by its fid. Objects are indexed
  71  *     by their fids (hash table is used for index).
  72  *
  73  * 2. caching and life-cycle management.
  74  *
  75  *     Object's life-time is controlled by reference counting. When reference
  76  *     count drops to 0, object is returned to cache. Cached objects still
  77  *     retain their identity (i.e., fid), and can be recovered from cache.
  78  *
  79  *     Objects are kept in the global LRU list, and lu_site_purge() function
  80  *     can be used to reclaim given number of unused objects from the tail of
  81  *     the LRU.
  82  *
  83  * 3. avoiding recursion.
  84  *
  85  *     Generic code tries to replace recursion through layers by iterations
  86  *     where possible. Additionally to the end of reducing stack consumption,
  87  *     data, when practically possible, are allocated through lu_context_key
  88  *     interface rather than on stack.
  89  *
  90  */
  91
  92 struct lu_site;
  93 struct lu_object;
  94 struct lu_device;
  95 struct lu_object_header;
  96 struct lu_context;
  97 /*
  98  * Operations common for data and meta-data devices.
  99  */
 100 struct lu_device_operations {
 101         /*
 102          * Object creation protocol.
 103          *
 104          * Due to design goal of avoiding recursion, object creation (see
 105          * lu_object_alloc()) is somewhat involved:
 106          *
 107          *  - first, ->ldo_object_alloc() method of the top-level device
 108          *  in the stack is called. It should allocate top level object
 109          *  (including lu_object_header), but without any lower-layer
 110          *  sub-object(s).
 111          *
 112          *  - then lu_object_alloc() sets fid in the header of newly created
 113          *  object.
 114          *
 115          *  - then ->loo_object_init() (a method from struct
 116          *  lu_object_operations) is called. It has to allocate lower-layer
 117          *  object(s). To do this, ->loo_object_init() calls
 118          *  ldo_object_alloc() of the lower-layer device(s).
 119          *
 120          *  - for all new objects allocated by ->loo_object_init() (and
 121          *  inserted into object stack), ->loo_object_init() is called again
 122          *  repeatedly, until no new objects are created.
 123          *
 124          */
 125
 126         /*
 127          * Allocate object for the given device (without lower-layer
 128          * parts). This is called by ->loo_object_init() from the parent
 129          * layer, and should setup at least ->lo_dev and ->lo_ops fields of
 130          * resulting lu_object.
 131          *
 132          * postcondition: ergo(!IS_ERR(result), result->lo_dev ==  d &&
 133          *                                      result->lo_ops != NULL);
 134          */
 135         struct lu_object *(*ldo_object_alloc)(const struct lu_context *ctx,
 136                                               const struct lu_object_header *h,
 137                                               struct lu_device *d);
 138         /*
 139          * process config specific for device
 140          */
 141         int  (*ldo_process_config)(const struct lu_context *ctx,
 142                                    struct lu_device *, struct lustre_cfg *);
 143
 144 };
 145
 146 /*
 147  * Type of "printer" function used by ->loo_object_print() method.
 148  *
 149  * Printer function is needed to provide some flexibility in (semi-)debugging
 150  * output: possible implementations: printk, CDEBUG, sysfs/seq_file
 151  */
 152 typedef int (*lu_printer_t)(const struct lu_context *ctx,
 153                             void *cookie, const char *format, ...)
 154         __attribute__ ((format (printf, 3, 4)));
 155
 156 /*
 157  * Operations specific for particular lu_object.
 158  */
 159 struct lu_object_operations {
 160
 161         /*
 162          * Allocate lower-layer parts of the object by calling
 163          * ->ldo_object_alloc() of the corresponding underlying device.
 164          *
 165          * This method is called once for each object inserted into object
 166          * stack. It's responsibility of this method to insert lower-layer
 167          * object(s) it create into appropriate places of object stack.
 168          */
 169         int (*loo_object_init)(const struct lu_context *ctx,
 170                                struct lu_object *o);
 171         /*
 172          * Called before ->loo_object_free() to signal that object is being
 173          * destroyed. Dual to ->loo_object_init().
 174          */
 175         void (*loo_object_delete)(const struct lu_context *ctx,
 176                                   struct lu_object *o);
 177
 178         /*
 179          * Dual to ->ldo_object_alloc(). Called when object is removed from
 180          * memory.
 181          */
 182         void (*loo_object_free)(const struct lu_context *ctx,
 183                                 struct lu_object *o);
 184
 185         /*
 186          * Called when last active reference to the object is released (and
 187          * object returns to the cache). This method is optional.
 188          */
 189         void (*loo_object_release)(const struct lu_context *ctx,
 190                                    struct lu_object *o);
 191
 192         /*
 193          * Return true off object @o exists on a storage.
 194          */
 195         int (*loo_object_exists)(const struct lu_context *ctx,
 196                                  const struct lu_object *o);
 197         /*
 198          * Debugging helper. Print given object.
 199          */
 200         int (*loo_object_print)(const struct lu_context *ctx, void *cookie,
 201                                 lu_printer_t p, const struct lu_object *o);
 202         /*
 203          * Optional debugging method. Returns true iff method is internally
 204          * consistent.
 205          */
 206         int (*loo_object_invariant)(const struct lu_object *o);
 207 };
 208
 209 /*
 210  * Type of lu_device.
 211  */
 212 struct lu_device_type;
 213
 214 /*
 215  * Device: a layer in the server side abstraction stacking.
 216  */
 217 struct lu_device {
 218         /*
 219          * reference count. This is incremented, in particular, on each object
 220          * created at this layer.
 221          *
 222          * XXX which means that atomic_t is probably too small.
 223          */
 224         atomic_t                     ld_ref;
 225         /*
 226          * Pointer to device type. Never modified once set.
 227          */
 228         struct lu_device_type       *ld_type;
 229         /*
 230          * Operation vector for this device.
 231          */
 232         struct lu_device_operations *ld_ops;
 233         /*
 234          * Stack this device belongs to.
 235          */
 236         struct lu_site              *ld_site;
 237         struct proc_dir_entry       *ld_proc_entry;
 238
 239         /* XXX: temporary back pointer into obd. */
 240         struct obd_device           *ld_obd;
 241 };
 242
 243 struct lu_device_type_operations;
 244
 245 /*
 246  * Tag bits for device type. They are used to distinguish certain groups of
 247  * device types.
 248  */
 249 enum lu_device_tag {
 250         /* this is meta-data device */
 251         LU_DEVICE_MD = (1 << 0),
 252         /* this is data device */
 253         LU_DEVICE_DT = (1 << 1)
 254 };
 255
 256 /*
 257  * Type of device.
 258  */
 259 struct lu_device_type {
 260         /*
 261          * Tag bits. Taken from enum lu_device_tag. Never modified once set.
 262          */
 263         __u32                             ldt_tags;
 264         /*
 265          * Name of this class. Unique system-wide. Never modified once set.
 266          */
 267         char                             *ldt_name;
 268         /*
 269          * Operations for this type.
 270          */
 271         struct lu_device_type_operations *ldt_ops;
 272         /*
 273          * XXX: temporary pointer to associated obd_type.
 274          */
 275         struct obd_type                  *ldt_obd_type;
 276         /*
 277          * XXX: temporary: context tags used by obd_*() calls.
 278          */
 279         __u32                             ldt_ctx_tags;
 280 };
 281
 282 /*
 283  * Operations on a device type.
 284  */
 285 struct lu_device_type_operations {
 286         /*
 287          * Allocate new device.
 288          */
 289         struct lu_device *(*ldto_device_alloc)(const struct lu_context *ctx,
 290                                                struct lu_device_type *t,
 291                                                struct lustre_cfg *lcfg);
 292         /*
 293          * Free device. Dual to ->ldto_device_alloc().
 294          */
 295         void (*ldto_device_free)(const struct lu_context *ctx,
 296                                  struct lu_device *d);
 297
 298         /*
 299          * Initialize the devices after allocation
 300          */
 301         int  (*ldto_device_init)(const struct lu_context *ctx,
 302                                  struct lu_device *, struct lu_device *);
 303         /*
 304          * Finalize device. Dual to ->ldto_device_init(). Returns pointer to
 305          * the next device in the stack.
 306          */
 307         struct lu_device *(*ldto_device_fini)(const struct lu_context *ctx,
 308                                               struct lu_device *);
 309
 310         /*
 311          * Initialize device type. This is called on module load.
 312          */
 313         int  (*ldto_init)(struct lu_device_type *t);
 314         /*
 315          * Finalize device type. Dual to ->ldto_init(). Called on module
 316          * unload.
 317          */
 318         void (*ldto_fini)(struct lu_device_type *t);
 319 };
 320
 321 /*
 322  * Flags for the object layers.
 323  */
 324 enum lu_object_flags {
 325         /*
 326          * this flags is set if ->loo_object_init() has been called for this
 327          * layer. Used by lu_object_alloc().
 328          */
 329         LU_OBJECT_ALLOCATED = (1 << 0)
 330 };
 331
 332 /*
 333  * Common object attributes.
 334  */
 335 /* valid flags */
 336 enum la_valid {
 337         LA_ATIME  = OBD_MD_FLATIME,
 338         LA_MTIME  = OBD_MD_FLMTIME,
 339         LA_CTIME  = OBD_MD_FLCTIME,
 340         LA_SIZE   = OBD_MD_FLSIZE,
 341         LA_BLOCKS = OBD_MD_FLBLOCKS,
 342         LA_MODE   = OBD_MD_FLMODE,
 343         LA_TYPE   = OBD_MD_FLTYPE,
 344         LA_UID    = OBD_MD_FLUID,
 345         LA_GID    = OBD_MD_FLGID,
 346         LA_FLAGS  = OBD_MD_FLFLAGS,
 347         LA_NLINK  = OBD_MD_FLNLINK,
 348         LA_RDEV   = OBD_MD_FLRDEV,
 349 };
 350
 351 struct lu_attr {
 352         __u64          la_size;   /* size in bytes */
 353         __u64          la_mtime;  /* modification time in seconds since Epoch */
 354         __u64          la_atime;  /* access time in seconds since Epoch */
 355         __u64          la_ctime;  /* change time in seconds since Epoch */
 356         __u64          la_blocks; /* 512-byte blocks allocated to object */
 357         __u32          la_mode;   /* permission bits and file type */
 358         __u32          la_uid;    /* owner id */
 359         __u32          la_gid;    /* group id */
 360         __u32          la_flags;  /* object flags */
 361         __u32          la_nlink;  /* number of persistent references to this
 362                                    * object */
 363         __u32          la_rdev;   /* real device */
 364         __u64          la_valid;  /* valid bits */
 365 };
 366
 367
 368 /*
 369  * Layer in the layered object.
 370  */
 371 struct lu_object {
 372         /*
 373          * Header for this object.
 374          */
 375         struct lu_object_header     *lo_header;
 376         /*
 377          * Device for this layer.
 378          */
 379         struct lu_device            *lo_dev;
 380         /*
 381          * Operations for this object.
 382          */
 383         struct lu_object_operations *lo_ops;
 384         /*
 385          * Linkage into list of all layers.
 386          */
 387         struct list_head             lo_linkage;
 388         /*
 389          * Depth. Top level layer depth is 0.
 390          */
 391         int                          lo_depth;
 392         /*
 393          * Flags from enum lu_object_flags.
 394          */
 395         unsigned long                lo_flags;
 396 };
 397
 398 enum lu_object_header_flags {
 399         /*
 400          * Don't keep this object in cache. Object will be destroyed as soon
 401          * as last reference to it is released. This flag cannot be cleared
 402          * once set.
 403          */
 404         LU_OBJECT_HEARD_BANSHEE = 0,
 405 };
 406
 407 /*
 408  * "Compound" object, consisting of multiple layers.
 409  *
 410  * Compound object with given fid is unique with given lu_site.
 411  *
 412  * Note, that object does *not* necessary correspond to the real object in the
 413  * persistent storage: object is an anchor for locking and method calling, so
 414  * it is created for things like not-yet-existing child created by mkdir or
 415  * create calls. ->loo_exists() can be used to check whether object is backed
 416  * by persistent storage entity.
 417  */
 418 struct lu_object_header {
 419         /*
 420          * Object flags from enum lu_object_header_flags. Set and checked
 421          * atomically.
 422          */
 423         unsigned long     loh_flags;
 424         /*
 425          * Object reference count. Protected by site guard lock.
 426          */
 427         int               loh_ref;
 428         /*
 429          * Fid, uniquely identifying this object.
 430          */
 431         struct lu_fid     loh_fid;
 432         /*
 433          * Linkage into per-site hash table. Protected by site guard lock.
 434          */
 435         struct hlist_node loh_hash;
 436         /*
 437          * Linkage into per-site LRU list. Protected by site guard lock.
 438          */
 439         struct list_head  loh_lru;
 440         /*
 441          * Linkage into list of layers. Never modified once set (except lately
 442          * during object destruction). No locking is necessary.
 443          */
 444         struct list_head  loh_layers;
 445 };
 446
 447 struct fld;
 448
 449 /*
 450  * lu_site is a "compartment" within which objects are unique, and LRU
 451  * discipline is maintained.
 452  *
 453  * lu_site exists so that multiple layered stacks can co-exist in the same
 454  * address space.
 455  *
 456  * lu_site has the same relation to lu_device as lu_object_header to
 457  * lu_object.
 458  */
 459 struct lu_site {
 460         /*
 461          * lock protecting:
 462          *
 463          *        - ->ls_hash hash table (and its linkages in objects);
 464          *
 465          *        - ->ls_lru list (and its linkages in objects);
 466          *
 467          *        - 0/1 transitions of object ->loh_ref reference count;
 468          *
 469          * yes, it's heavy.
 470          */
 471         spinlock_t            ls_guard;
 472         /*
 473          * Hash-table where objects are indexed by fid.
 474          */
 475         struct hlist_head    *ls_hash;
 476         /*
 477          * Bit-mask for hash-table size.
 478          */
 479         int                   ls_hash_mask;
 480
 481
 482         /*
 483          * LRU list, updated on each access to object. Protected by
 484          * ->ls_guard.
 485          *
 486          * "Cold" end of LRU is ->ls_lru.next. Accessed object are moved to
 487          * the ->ls_lru.prev (this is due to the non-existence of
 488          * list_for_each_entry_safe_reverse()).
 489          */
 490         struct list_head      ls_lru;
 491         /*
 492          * Total number of objects in this site. Protected by ->ls_guard.
 493          */
 494         unsigned              ls_total;
 495         /*
 496          * Total number of objects in this site with reference counter greater
 497          * than 0. Protected by ->ls_guard.
 498          */
 499         unsigned              ls_busy;
 500
 501         /*
 502          * Top-level device for this stack.
 503          */
 504         struct lu_device     *ls_top_dev;
 505         /*
 506          * mds number of this site.
 507          */
 508         mdsno_t               ls_node_id;
 509         /*
 510          * Fid location database
 511          */
 512         struct lu_server_fld *ls_server_fld;
 513         struct lu_client_fld *ls_client_fld;
 514
 515         /*
 516          * Server Seq Manager
 517          */
 518         struct lu_server_seq *ls_server_seq;
 519
 520         /*
 521          * Controller Seq Manager
 522          */
 523         struct lu_server_seq *ls_ctlr_seq;
 524
 525         /*
 526          * Clienbt Seq Manager
 527          */
 528         struct lu_client_seq *ls_client_seq;
 529
 530         /* sequence controller node */
 531         struct obd_export    *ls_ctlr_exp;
 532
 533         /* statistical counters. Protected by nothing, races are accepted. */
 534         struct {
 535                 __u32 s_created;
 536                 __u32 s_cache_hit;
 537                 __u32 s_cache_miss;
 538                 /*
 539                  * Number of hash-table entry checks made.
 540                  *
 541                  *       ->s_cache_check / (->s_cache_miss + ->s_cache_hit)
 542                  *
 543                  * is an average number of hash slots inspected during single
 544                  * lookup.
 545                  */
 546                 __u32 s_cache_check;
 547                 /* raced cache insertions */
 548                 __u32 s_cache_race;
 549                 __u32 s_lru_purged;
 550         } ls_stats;
 551 };
 552
 553 /*
 554  * Constructors/destructors.
 555  */
 556
 557 /*
 558  * Initialize site @s, with @d as the top level device.
 559  */
 560 int  lu_site_init(struct lu_site *s, struct lu_device *d);
 561 /*
 562  * Finalize @s and release its resources.
 563  */
 564 void lu_site_fini(struct lu_site *s);
 565
 566 /*
 567  * Acquire additional reference on device @d
 568  */
 569 void lu_device_get(struct lu_device *d);
 570 /*
 571  * Release reference on device @d.
 572  */
 573 void lu_device_put(struct lu_device *d);
 574
 575 /*
 576  * Initialize device @d of type @t.
 577  */
 578 int lu_device_init(struct lu_device *d, struct lu_device_type *t);
 579 /*
 580  * Finalize device @d.
 581  */
 582 void lu_device_fini(struct lu_device *d);
 583
 584 /*
 585  * Initialize compound object.
 586  */
 587 int lu_object_header_init(struct lu_object_header *h);
 588 /*
 589  * Finalize compound object.
 590  */
 591 void lu_object_header_fini(struct lu_object_header *h);
 592
 593 /*
 594  * Initialize object @o that is part of compound object @h and was created by
 595  * device @d.
 596  */
 597 int lu_object_init(struct lu_object *o,
 598                    struct lu_object_header *h, struct lu_device *d);
 599 /*
 600  * Finalize object and release its resources.
 601  */
 602 void lu_object_fini(struct lu_object *o);
 603 /*
 604  * Add object @o as first layer of compound object @h.
 605  *
 606  * This is typically called by the ->ldo_object_alloc() method of top-level
 607  * device.
 608  */
 609 void lu_object_add_top(struct lu_object_header *h, struct lu_object *o);
 610 /*
 611  * Add object @o as a layer of compound object, going after @before.1
 612  *
 613  * This is typically called by the ->ldo_object_alloc() method of
 614  * @before->lo_dev.
 615  */
 616 void lu_object_add(struct lu_object *before, struct lu_object *o);
 617
 618 /*
 619  * Caching and reference counting.
 620  */
 621
 622 /*
 623  * Acquire additional reference to the given object. This function is used to
 624  * attain additional reference. To acquire initial reference use
 625  * lu_object_find().
 626  */
 627 static inline void lu_object_get(struct lu_object *o)
 628 {
 629         LASSERT(o->lo_header->loh_ref > 0);
 630         spin_lock(&o->lo_dev->ld_site->ls_guard);
 631         o->lo_header->loh_ref ++;
 632         spin_unlock(&o->lo_dev->ld_site->ls_guard);
 633 }
 634
 635 /*
 636  * Return true of object will not be cached after last reference to it is
 637  * released.
 638  */
 639 static inline int lu_object_is_dying(const struct lu_object_header *h)
 640 {
 641         return test_bit(LU_OBJECT_HEARD_BANSHEE, &h->loh_flags);
 642 }
 643
 644 /*
 645  * Decrease reference counter on object. If last reference is freed, return
 646  * object to the cache, unless lu_object_is_dying(o) holds. In the latter
 647  * case, free object immediately.
 648  */
 649 void lu_object_put(const struct lu_context *ctxt,
 650                    struct lu_object *o);
 651
 652 /*
 653  * Free @nr objects from the cold end of the site LRU list.
 654  */
 655 void lu_site_purge(const struct lu_context *ctx,
 656                    struct lu_site *s, int nr);
 657
 658 /*
 659  * Search cache for an object with the fid @f. If such object is found, return
 660  * it. Otherwise, create new object, insert it into cache and return it. In
 661  * any case, additional reference is acquired on the returned object.
 662  */
 663 struct lu_object *lu_object_find(const struct lu_context *ctxt,
 664                                  struct lu_site *s, const struct lu_fid *f);
 665
 666 /*
 667  * Helpers.
 668  */
 669
 670 /*
 671  * First (topmost) sub-object of given compound object
 672  */
 673 static inline struct lu_object *lu_object_top(struct lu_object_header *h)
 674 {
 675         LASSERT(!list_empty(&h->loh_layers));
 676         return container_of0(h->loh_layers.next, struct lu_object, lo_linkage);
 677 }
 678
 679 /*
 680  * Next sub-object in the layering
 681  */
 682 static inline struct lu_object *lu_object_next(const struct lu_object *o)
 683 {
 684         return container_of0(o->lo_linkage.next, struct lu_object, lo_linkage);
 685 }
 686
 687 /*
 688  * Pointer to the fid of this object.
 689  */
 690 static inline const struct lu_fid *lu_object_fid(const struct lu_object *o)
 691 {
 692         return &o->lo_header->loh_fid;
 693 }
 694
 695 /*
 696  * return device operations vector for this object
 697  */
 698 static inline struct lu_device_operations *
 699 lu_object_ops(const struct lu_object *o)
 700 {
 701         return o->lo_dev->ld_ops;
 702 }
 703
 704 /*
 705  * Given a compound object, find its slice, corresponding to the device type
 706  * @dtype.
 707  */
 708 struct lu_object *lu_object_locate(struct lu_object_header *h,
 709                                    struct lu_device_type *dtype);
 710
 711 struct lu_cdebug_print_info {
 712         int         lpi_subsys;
 713         int         lpi_mask;
 714         const char *lpi_file;
 715         const char *lpi_fn;
 716         int         lpi_line;
 717 };
 718
 719 /*
 720  * Printer function emitting messages through libcfs_debug_msg().
 721  */
 722 int lu_cdebug_printer(const struct lu_context *ctx,
 723                       void *cookie, const char *format, ...);
 724
 725 /*
 726  * Print object description followed by user-supplied message.
 727  */
 728 #define LU_OBJECT_DEBUG(mask, ctx, object, format, ...)                 \
 729 ({                                                                      \
 730         static struct lu_cdebug_print_info __info = {                   \
 731                 .lpi_subsys = DEBUG_SUBSYSTEM,                          \
 732                 .lpi_mask   = (mask),                                   \
 733                 .lpi_file   = __FILE__,                                 \
 734                 .lpi_fn     = __FUNCTION__,                             \
 735                 .lpi_line   = __LINE__                                  \
 736         };                                                              \
 737         lu_object_print(ctx, &__info, lu_cdebug_printer, object);       \
 738         CDEBUG(mask, format , ## __VA_ARGS__);                          \
 739 })
 740
 741 /*
 742  * Print human readable representation of the @o to the @f.
 743  */
 744 void lu_object_print(const struct lu_context *ctxt, void *cookie,
 745                      lu_printer_t printer, const struct lu_object *o);
 746
 747 /*
 748  * Check object consistency.
 749  */
 750 int lu_object_invariant(const struct lu_object *o);
 751
 752 /*
 753  * Returns 1 iff object @o exists on the stable storage,
 754  * returns -1 iff object @o is on remote server.
 755  */
 756 static inline int lu_object_exists(const struct lu_context *ctx,
 757                                    const struct lu_object *o)
 758 {
 759         return o->lo_ops->loo_object_exists(ctx, o);
 760 }
 761
 762 static inline int lu_object_assert_exists(const struct lu_context *ctx,
 763                                           const struct lu_object *o)
 764 {
 765         return lu_object_exists(ctx, o) != 0;
 766 }
 767
 768 static inline int lu_object_assert_not_exists(const struct lu_context *ctx,
 769                                               const struct lu_object *o)
 770 {
 771         return lu_object_exists(ctx, o) <= 0;
 772 }
 773
 774 struct lu_rdpg {
 775         /* input params, should be filled out by mdt */
 776         __u32                   rp_hash;        /* hash */
 777         int                     rp_count;       /* count in bytes       */
 778         int                     rp_npages;      /* number of pages      */
 779         struct page           **rp_pages;       /* pointers to pages    */
 780 };
 781
 782 enum lu_xattr_flags {
 783         LU_XATTR_REPLACE = (1 << 0),
 784         LU_XATTR_CREATE  = (1 << 1)
 785 };
 786
 787 /*
 788  * lu_context. Execution context for lu_object methods. Currently associated
 789  * with thread.
 790  *
 791  * All lu_object methods, except device and device type methods (called during
 792  * system initialization and shutdown) are executed "within" some
 793  * lu_context. This means, that pointer to some "current" lu_context is passed
 794  * as an argument to all methods.
 795  *
 796  * All service ptlrpc threads create lu_context as part of their
 797  * initialization. It is possible to create "stand-alone" context for other
 798  * execution environments (like system calls).
 799  *
 800  * lu_object methods mainly use lu_context through lu_context_key interface
 801  * that allows each layer to associate arbitrary pieces of data with each
 802  * context (see pthread_key_create(3) for similar interface).
 803  *
 804  */
 805 struct lu_context {
 806         /*
 807          * Theoretically we'd want to use lu_objects and lu_contexts on the
 808          * client side too. On the other hand, we don't want to allocate
 809          * values of server-side keys for the client contexts and vice versa.
 810          *
 811          * To achieve this, set of tags in introduced. Contexts and keys are
 812          * marked with tags. Key value are created only for context whose set
 813          * of tags has non-empty intersection with one for key. Tags are taken
 814          * from enum lu_context_tag.
 815          */
 816         __u32                  lc_tags;
 817         /*
 818          * Pointer to the home service thread. NULL for other execution
 819          * contexts.
 820          */
 821         struct ptlrpc_thread  *lc_thread;
 822         /*
 823          * Pointer to an array with key values. Internal implementation
 824          * detail.
 825          */
 826         void                 **lc_value;
 827 };
 828
 829 /*
 830  * lu_context_key interface. Similar to pthread_key.
 831  */
 832
 833 enum lu_context_tag {
 834         LCT_MD_THREAD = 1 << 0,
 835         LCT_DT_THREAD = 1 << 1,
 836         LCT_TX_HANDLE = 1 << 2,
 837         LCT_CL_THREAD = 1 << 3
 838 };
 839
 840 /*
 841  * Key. Represents per-context value slot.
 842  */
 843 struct lu_context_key {
 844         /*
 845          * Set of tags for which values of this key are to be instantiated.
 846          */
 847         __u32 lct_tags;
 848         /*
 849          * Value constructor. This is called when new value is created for a
 850          * context. Returns pointer to new value of error pointer.
 851          */
 852         void  *(*lct_init)(const struct lu_context *ctx,
 853                            struct lu_context_key *key);
 854         /*
 855          * Value destructor. Called when context with previously allocated
 856          * value of this slot is destroyed. @data is a value that was returned
 857          * by a matching call to ->lct_init().
 858          */
 859         void   (*lct_fini)(const struct lu_context *ctx,
 860                            struct lu_context_key *key, void *data);
 861         /*
 862          * Internal implementation detail: index within ->lc_value[] reserved
 863          * for this key.
 864          */
 865         int      lct_index;
 866         /*
 867          * Internal implementation detail: number of values created for this
 868          * key.
 869          */
 870         unsigned lct_used;
 871 };
 872
 873 /*
 874  * Register new key.
 875  */
 876 int   lu_context_key_register(struct lu_context_key *key);
 877 /*
 878  * Deregister key.
 879  */
 880 void  lu_context_key_degister(struct lu_context_key *key);
 881 /*
 882  * Return value associated with key @key in context @ctx.
 883  */
 884 void *lu_context_key_get(const struct lu_context *ctx,
 885                          struct lu_context_key *key);
 886
 887 /*
 888  * Initialize context data-structure. Create values for all keys.
 889  */
 890 int  lu_context_init(struct lu_context *ctx, __u32 tags);
 891 /*
 892  * Finalize context data-structure. Destroy key values.
 893  */
 894 void lu_context_fini(struct lu_context *ctx);
 895
 896 /*
 897  * Called before entering context.
 898  */
 899 void lu_context_enter(struct lu_context *ctx);
 900 /*
 901  * Called after exiting from @ctx
 902  */
 903 void lu_context_exit(struct lu_context *ctx);
 904
 905 /*
 906  * One-time initializers, called at obdclass module initialization, not
 907  * exported.
 908  */
 909
 910 /*
 911  * Initialization of global lu_* data.
 912  */
 913 int lu_global_init(void);
 914
 915 /*
 916  * Dual to lu_global_init().
 917  */
 918 void lu_global_fini(void);
 919
 920 #endif /* __LUSTRE_LU_OBJECT_H */