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