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