src/vol/volume_inline.h

   1 /*
   2  * Copyright 2005-2008, Sine Nomine Associates and others.
   3  * All Rights Reserved.
   4  *
   5  * This software has been released under the terms of the IBM Public
   6  * License.  For details, see the LICENSE file in the top-level source
   7  * directory or online at http://www.openafs.org/dl/license10.html
   8  */
   9
  10 #ifndef _AFS_VOL_VOLUME_INLINE_H
  11 #define _AFS_VOL_VOLUME_INLINE_H 1
  12
  13 #include "volume.h"
  14 #include "partition.h"
  15
  16 #if defined(AFS_DEMAND_ATTACH_FS) || defined(AFS_DEMAND_ATTACH_UTIL)
  17 # include "lock.h"
  18 #endif
  19
  20 #ifdef AFS_PTHREAD_ENV
  21 /**
  22  * @param[in] cv cond var
  23  * @param[in] ts deadline, or NULL to wait forever
  24  * @param[out] timedout  set to 1 if we returned due to the deadline, 0 if we
  25  *                       returned due to the cond var getting signalled. If
  26  *                       NULL, it is ignored.
  27  */
  28 static_inline void
  29 VOL_CV_TIMEDWAIT(pthread_cond_t *cv, const struct timespec *ts, int *timedout)
  30 {
  31     int code;
  32     if (timedout) {
  33         *timedout = 0;
  34     }
  35     if (!ts) {
  36         VOL_CV_WAIT(cv);
  37         return;
  38     }
  39     VOL_LOCK_DBG_CV_WAIT_BEGIN;
  40     code = CV_TIMEDWAIT(cv, &vol_glock_mutex, ts);
  41     VOL_LOCK_DBG_CV_WAIT_END;
  42     if (code == ETIMEDOUT) {
  43         code = 0;
  44         if (timedout) {
  45             *timedout = 1;
  46         }
  47     }
  48     osi_Assert(code == 0);
  49 }
  50 #endif /* AFS_PTHREAD_ENV */
  51
  52 /**
  53  * tell caller whether the given program type represents a salvaging
  54  * program.
  55  *
  56  * @param type  program type enumeration
  57  *
  58  * @return whether program state is a salvager
  59  *   @retval 0  type is a non-salvaging program
  60  *   @retval 1  type is a salvaging program
  61  */
  62 static_inline int
  63 VIsSalvager(ProgramType type)
  64 {
  65     switch(type) {
  66     case salvager:
  67     case salvageServer:
  68     case volumeSalvager:
  69         return 1;
  70     default:
  71         return 0;
  72     }
  73 }
  74
  75 /**
  76  * tells caller whether or not we need to lock the entire partition when
  77  * attaching a volume.
  78  *
  79  * @return whether or not we need to lock the partition
  80  *  @retval 0  no, we do not
  81  *  @retval 1  yes, we do
  82  *
  83  * @note for DAFS, always returns 0, since we use per-header locks instead
  84  */
  85 static_inline int
  86 VRequiresPartLock(void)
  87 {
  88 #if defined(AFS_DEMAND_ATTACH_FS) || defined(AFS_DEMAND_ATTACH_UTIL)
  89     return 0;
  90 #else
  91     switch (programType) {
  92     case volumeServer:
  93     case volumeUtility:
  94         return 1;
  95     default:
  96         return 0;
  97     }
  98 #endif /* AFS_DEMAND_ATTACH_FS || AFS_DEMAND_ATTACH_UTIL */
  99 }
 100
 101 /**
 102  * tells caller whether or not we need to check out a volume from the
 103  * fileserver before we can use it.
 104  *
 105  * @param[in] mode the mode of attachment for the volume
 106  *
 107  * @return whether or not we need to check out the volume from the fileserver
 108  *  @retval 0 no, we can just use the volume
 109  *  @retval 1 yes, we must check out the volume before use
 110  */
 111 static_inline int
 112 VMustCheckoutVolume(int mode)
 113 {
 114     if (VCanUseFSSYNC() && mode != V_SECRETLY && mode != V_PEEK) {
 115         return 1;
 116     }
 117     return 0;
 118 }
 119
 120 /**
 121  * tells caller whether we should check the inUse field in the volume
 122  * header when attaching a volume.
 123  *
 124  * If we check inUse, that generally means we will salvage the volume
 125  * (or put it in an error state) if we detect that another program
 126  * claims to be using the volume when we try to attach. We don't always
 127  * want to do that, since sometimes we know that the volume may be in
 128  * use by another program, e.g. when we are attaching with V_PEEK, and
 129  * we don't care.
 130  *
 131  * @param mode  the mode of attachment for the volume
 132  *
 133  * @return whether or not we should check inUse
 134  *  @retval 0  no, we should not check inUse
 135  *  @retval 1  yes, we should check inUse
 136  */
 137 static_inline int
 138 VShouldCheckInUse(int mode)
 139 {
 140     if (VCanUnsafeAttach()) {
 141         return 0;
 142     }
 143     if (programType == fileServer) {
 144        return 1;
 145     }
 146     if (VMustCheckoutVolume(mode)) {
 147         /* assume we checked out the volume from the fileserver, so inUse
 148          * should not be set */
 149         return 1;
 150     }
 151     return 0;
 152 }
 153
 154 #if defined(AFS_DEMAND_ATTACH_FS) || defined(AFS_DEMAND_ATTACH_UTIL)
 155 /**
 156  * acquire a non-blocking disk lock for a particular volume id.
 157  *
 158  * @param[in] volid the volume ID to lock
 159  * @param[in] dp    the partition on which 'volid' resides
 160  * @param[in] locktype READ_LOCK or WRITE_LOCK
 161  *
 162  * @return operation status
 163  *  @retval 0 success, lock was obtained
 164  *  @retval EBUSY another process holds a conflicting lock
 165  *  @retval EIO   error acquiring lock
 166  *
 167  * @note Use VLockVolumeNB instead, if possible; only use this directly if
 168  * you are not dealing with 'Volume*'s and attached volumes and such
 169  *
 170  * @pre There must not be any other threads acquiring locks on the same volid
 171  * and partition; the locks will not work correctly if two threads try to
 172  * acquire locks for the same volume
 173  */
 174 static_inline int
 175 VLockVolumeByIdNB(VolumeId volid, struct DiskPartition64 *dp, int locktype)
 176 {
 177     return VLockFileLock(&dp->volLockFile, volid, locktype, 1 /* nonblock */);
 178 }
 179
 180 /**
 181  * release a lock acquired by VLockVolumeByIdNB.
 182  *
 183  * @param[in] volid the volume id to unlock
 184  * @param[in] dp    the partition on which 'volid' resides
 185  *
 186  * @pre volid was previously locked by VLockVolumeByIdNB
 187  */
 188 static_inline void
 189 VUnlockVolumeById(VolumeId volid, struct DiskPartition64 *dp)
 190 {
 191     VLockFileUnlock(&dp->volLockFile, volid);
 192 }
 193
 194 /***************************************************/
 195 /* demand attach fs state machine routines         */
 196 /***************************************************/
 197
 198 /**
 199  * tells caller whether we need to keep volumes locked for the entire time we
 200  * are using them, or if we can unlock volumes as soon as they are attached.
 201  *
 202  * @return whether we can unlock attached volumes or not
 203  *  @retval 1 yes, we can unlock attached volumes
 204  *  @retval 0 no, do not unlock volumes until we unattach them
 205  */
 206 static_inline int
 207 VCanUnlockAttached(void)
 208 {
 209     switch(programType) {
 210     case fileServer:
 211         return 1;
 212     default:
 213         return 0;
 214     }
 215 }
 216
 217 /**
 218  * tells caller whether we need to lock a vol header with a write lock, a
 219  * read lock, or if we do not need to lock it at all, when attaching.
 220  *
 221  * @param[in]  mode  volume attachment mode
 222  * @param[in]  writeable  1 if the volume is writable, 0 if not
 223  *
 224  * @return how we need to lock the vol header
 225  *  @retval 0 do not lock the vol header at all
 226  *  @retval READ_LOCK lock the vol header with a read lock
 227  *  @retval WRITE_LOCK lock the vol header with a write lock
 228  *
 229  * @note DAFS only (non-DAFS uses partition locks)
 230  */
 231 static_inline int
 232 VVolLockType(int mode, int writeable)
 233 {
 234     switch (programType) {
 235     case fileServer:
 236         if (writeable) {
 237             return WRITE_LOCK;
 238         }
 239         return READ_LOCK;
 240
 241     case volumeSalvager:
 242     case salvageServer:
 243     case salvager:
 244         return WRITE_LOCK;
 245
 246     default:
 247         /* volserver, vol utilies, etc */
 248
 249         switch (mode) {
 250         case V_READONLY:
 251             return READ_LOCK;
 252
 253         case V_VOLUPD:
 254         case V_SECRETLY:
 255             return WRITE_LOCK;
 256
 257         case V_CLONE:
 258         case V_DUMP:
 259             if (writeable) {
 260                 return WRITE_LOCK;
 261             }
 262             return READ_LOCK;
 263
 264         case V_PEEK:
 265             return 0;
 266
 267         default:
 268             osi_Assert(0 /* unknown checkout mode */);
 269             return 0;
 270         }
 271     }
 272 }
 273 #endif /* AFS_DEMAND_ATTACH_FS || AFS_DEMAND_ATTACH_UTIL */
 274
 275 #ifdef AFS_DEMAND_ATTACH_FS
 276
 277 /**
 278  * tells caller whether or not the volume is effectively salvaging.
 279  *
 280  * @param vp  volume pointer
 281  *
 282  * @return whether volume is salvaging or not
 283  *  @retval 0 no, volume is not salvaging
 284  *  @retval 1 yes, volume is salvaging
 285  *
 286  * @note The volume may not actually be getting salvaged at the moment if
 287  *       this returns 1, but may have just been requested or scheduled to be
 288  *       salvaged. Callers should treat these cases as pretty much the same
 289  *       anyway, since we should not touch a volume that is busy salvaging or
 290  *       waiting to be salvaged.
 291  */
 292 static_inline int
 293 VIsSalvaging(struct Volume *vp)
 294 {
 295     /* these tests are a bit redundant, but to be safe... */
 296     switch(V_attachState(vp)) {
 297     case VOL_STATE_SALVAGING:
 298     case VOL_STATE_SALVAGE_REQ:
 299         return 1;
 300     default:
 301         if (vp->salvage.requested || vp->salvage.scheduled) {
 302             return 1;
 303         }
 304     }
 305     return 0;
 306 }
 307
 308 /**
 309  * tells caller whether or not the current state requires
 310  * exclusive access without holding glock.
 311  *
 312  * @param state  volume state enumeration
 313  *
 314  * @return whether volume state is a mutually exclusive state
 315  *   @retval 0  no, state is re-entrant
 316  *   @retval 1  yes, state is mutually exclusive
 317  *
 318  * @note DEMAND_ATTACH_FS only
 319  */
 320 static_inline int
 321 VIsExclusiveState(VolState state)
 322 {
 323     switch (state) {
 324     case VOL_STATE_UPDATING:
 325     case VOL_STATE_ATTACHING:
 326     case VOL_STATE_GET_BITMAP:
 327     case VOL_STATE_HDR_LOADING:
 328     case VOL_STATE_HDR_ATTACHING:
 329     case VOL_STATE_OFFLINING:
 330     case VOL_STATE_DETACHING:
 331     case VOL_STATE_SALVSYNC_REQ:
 332     case VOL_STATE_VNODE_ALLOC:
 333     case VOL_STATE_VNODE_GET:
 334     case VOL_STATE_VNODE_CLOSE:
 335     case VOL_STATE_VNODE_RELEASE:
 336     case VOL_STATE_VLRU_ADD:
 337     case VOL_STATE_SCANNING_RXCALLS:
 338         return 1;
 339     default:
 340         return 0;
 341     }
 342 }
 343
 344 /**
 345  * tell caller whether V_attachState is an error condition.
 346  *
 347  * @param state  volume state enumeration
 348  *
 349  * @return whether volume state is in error state
 350  *   @retval 0  state is not an error state
 351  *   @retval 1  state is an error state
 352  *
 353  * @note DEMAND_ATTACH_FS only
 354  */
 355 static_inline int
 356 VIsErrorState(VolState state)
 357 {
 358     switch (state) {
 359     case VOL_STATE_ERROR:
 360     case VOL_STATE_SALVAGING:
 361     case VOL_STATE_SALVAGE_REQ:
 362         return 1;
 363     default:
 364         return 0;
 365     }
 366 }
 367
 368 /**
 369  * tell caller whether V_attachState is an offline condition.
 370  *
 371  * @param state  volume state enumeration
 372  *
 373  * @return whether volume state is in offline state
 374  *   @retval 0  state is not an offline state
 375  *   @retval 1  state is an offline state
 376  *
 377  * @note DEMAND_ATTACH_FS only
 378  */
 379 static_inline int
 380 VIsOfflineState(VolState state)
 381 {
 382     switch (state) {
 383     case VOL_STATE_UNATTACHED:
 384     case VOL_STATE_ERROR:
 385     case VOL_STATE_SALVAGING:
 386     case VOL_STATE_DELETED:
 387         return 1;
 388     default:
 389         return 0;
 390     }
 391 }
 392
 393 /**
 394  * tell caller whether V_attachState is valid.
 395  *
 396  * @param state  volume state enumeration
 397  *
 398  * @return whether volume state is a mutually exclusive state
 399  *   @retval 0  no, state is not valid
 400  *   @retval 1  yes, state is a valid enumeration member
 401  *
 402  * @note DEMAND_ATTACH_FS only
 403  *
 404  * @note do we really want to treat VOL_STATE_FREED as valid?
 405  */
 406 static_inline int
 407 VIsValidState(VolState state)
 408 {
 409     if ((state >= 0) &&
 410         (state < VOL_STATE_COUNT)) {
 411         return 1;
 412     }
 413     return 0;
 414 }
 415
 416 /**
 417  * increment volume-package internal refcount.
 418  *
 419  * @param vp  volume object pointer
 420  *
 421  * @internal volume package internal use only
 422  *
 423  * @pre VOL_LOCK must be held
 424  *
 425  * @post volume waiters refcount is incremented
 426  *
 427  * @see VCancelReservation_r
 428  *
 429  * @note DEMAND_ATTACH_FS only
 430  */
 431 static_inline void
 432 VCreateReservation_r(Volume * vp)
 433 {
 434     vp->nWaiters++;
 435 }
 436
 437 /**
 438  * wait for the volume to change states.
 439  *
 440  * @param vp  volume object pointer
 441  *
 442  * @pre VOL_LOCK held; ref held on volume
 443  *
 444  * @post VOL_LOCK held; volume state has changed from previous value
 445  *
 446  * @note DEMAND_ATTACH_FS only
 447  */
 448 static_inline void
 449 VWaitStateChange_r(Volume * vp)
 450 {
 451     VolState state_save = V_attachState(vp);
 452
 453     osi_Assert(vp->nWaiters || vp->nUsers);
 454     do {
 455         VOL_CV_WAIT(&V_attachCV(vp));
 456     } while (V_attachState(vp) == state_save);
 457     osi_Assert(V_attachState(vp) != VOL_STATE_FREED);
 458 }
 459
 460 /**
 461  * wait for the volume to change states within a certain amount of time
 462  *
 463  * @param[in] vp  volume object pointer
 464  * @param[in] ts  deadline (absolute time) or NULL to wait forever
 465  *
 466  * @pre VOL_LOCK held; ref held on volume
 467  * @post VOL_LOCK held; volume state has changed and/or it is after the time
 468  *       specified in ts
 469  *
 470  * @note DEMAND_ATTACH_FS only
 471  * @note if ts is NULL, this is identical to VWaitStateChange_r
 472  */
 473 static_inline void
 474 VTimedWaitStateChange_r(Volume * vp, const struct timespec *ts, int *atimedout)
 475 {
 476     VolState state_save;
 477     int timeout;
 478
 479     if (atimedout) {
 480         *atimedout = 0;
 481     }
 482
 483     if (!ts) {
 484         VWaitStateChange_r(vp);
 485         return;
 486     }
 487
 488     state_save = V_attachState(vp);
 489
 490     assert(vp->nWaiters || vp->nUsers);
 491     do {
 492         VOL_CV_TIMEDWAIT(&V_attachCV(vp), ts, &timeout);
 493     } while (V_attachState(vp) == state_save && !timeout);
 494     assert(V_attachState(vp) != VOL_STATE_FREED);
 495
 496     if (atimedout && timeout) {
 497         *atimedout = 1;
 498     }
 499 }
 500
 501 /**
 502  * wait for blocking ops to end.
 503  *
 504  * @pre VOL_LOCK held; ref held on volume
 505  *
 506  * @post VOL_LOCK held; volume not in exclusive state
 507  *
 508  * @param vp  volume object pointer
 509  *
 510  * @note DEMAND_ATTACH_FS only
 511  */
 512 static_inline void
 513 VWaitExclusiveState_r(Volume * vp)
 514 {
 515     osi_Assert(vp->nWaiters || vp->nUsers);
 516     while (VIsExclusiveState(V_attachState(vp))) {
 517         VOL_CV_WAIT(&V_attachCV(vp));
 518     }
 519     osi_Assert(V_attachState(vp) != VOL_STATE_FREED);
 520 }
 521
 522 /**
 523  * change state, and notify other threads,
 524  * return previous state to caller.
 525  *
 526  * @param vp         pointer to volume object
 527  * @param new_state  new volume state value
 528  * @pre VOL_LOCK held
 529  *
 530  * @post volume state changed; stats updated
 531  *
 532  * @return previous volume state
 533  *
 534  * @note DEMAND_ATTACH_FS only
 535  */
 536 static_inline VolState
 537 VChangeState_r(Volume * vp, VolState new_state)
 538 {
 539     VolState old_state = V_attachState(vp);
 540
 541     /* XXX profiling need to make sure these counters
 542      * don't kill performance... */
 543     VStats.state_levels[old_state]--;
 544     VStats.state_levels[new_state]++;
 545
 546     V_attachState(vp) = new_state;
 547     CV_BROADCAST(&V_attachCV(vp));
 548     return old_state;
 549 }
 550
 551 #endif /* AFS_DEMAND_ATTACH_FS */
 552
 553 #define VENUMCASE(en) \
 554     case en: return #en
 555
 556 /**
 557  * translate a ProgramType code to a string.
 558  *
 559  * @param[in] type ProgramType numeric code
 560  *
 561  * @return a human-readable string for that program type
 562  *  @retval "**UNKNOWN**" an unknown ProgramType was given
 563  */
 564 static_inline char *
 565 VPTypeToString(ProgramType type)
 566 {
 567     switch (type) {
 568         VENUMCASE(fileServer);
 569         VENUMCASE(volumeUtility);
 570         VENUMCASE(salvager);
 571         VENUMCASE(salvageServer);
 572         VENUMCASE(debugUtility);
 573         VENUMCASE(volumeServer);
 574         VENUMCASE(volumeSalvager);
 575     default:
 576         return "**UNKNOWN**";
 577     }
 578 }
 579
 580 #undef VENUMCASE
 581
 582 #endif /* _AFS_VOL_VOLUME_INLINE_H */