Commit | Line | Data |
---|---|---|
3241b1d3 JT |
1 | /* |
2 | * Copyright (C) 2011 Red Hat, Inc. | |
3 | * | |
4 | * This file is released under the GPL. | |
5 | */ | |
6 | ||
7 | #ifndef _LINUX_DM_TRANSACTION_MANAGER_H | |
8 | #define _LINUX_DM_TRANSACTION_MANAGER_H | |
9 | ||
10 | #include "dm-block-manager.h" | |
11 | ||
12 | struct dm_transaction_manager; | |
13 | struct dm_space_map; | |
14 | ||
15 | /*----------------------------------------------------------------*/ | |
16 | ||
17 | /* | |
18 | * This manages the scope of a transaction. It also enforces immutability | |
19 | * of the on-disk data structures by limiting access to writeable blocks. | |
20 | * | |
21 | * Clients should not fiddle with the block manager directly. | |
22 | */ | |
23 | ||
24 | void dm_tm_destroy(struct dm_transaction_manager *tm); | |
25 | ||
26 | /* | |
27 | * The non-blocking version of a transaction manager is intended for use in | |
28 | * fast path code that needs to do lookups e.g. a dm mapping function. | |
29 | * You create the non-blocking variant from a normal tm. The interface is | |
30 | * the same, except that most functions will just return -EWOULDBLOCK. | |
31 | * Methods that return void yet may block should not be called on a clone | |
32 | * viz. dm_tm_inc, dm_tm_dec. Call dm_tm_destroy() as you would with a normal | |
33 | * tm when you've finished with it. You may not destroy the original prior | |
34 | * to clones. | |
35 | */ | |
36 | struct dm_transaction_manager *dm_tm_create_non_blocking_clone(struct dm_transaction_manager *real); | |
37 | ||
38 | /* | |
39 | * We use a 2-phase commit here. | |
40 | * | |
a9d45396 JT |
41 | * i) Make all changes for the transaction *except* for the superblock. |
42 | * Then call dm_tm_pre_commit() to flush them to disk. | |
3241b1d3 | 43 | * |
a9d45396 JT |
44 | * ii) Lock your superblock. Update. Then call dm_tm_commit() which will |
45 | * unlock the superblock and flush it. No other blocks should be updated | |
46 | * during this period. Care should be taken to never unlock a partially | |
47 | * updated superblock; perform any operations that could fail *before* you | |
48 | * take the superblock lock. | |
3241b1d3 JT |
49 | */ |
50 | int dm_tm_pre_commit(struct dm_transaction_manager *tm); | |
a9d45396 | 51 | int dm_tm_commit(struct dm_transaction_manager *tm, struct dm_block *superblock); |
3241b1d3 JT |
52 | |
53 | /* | |
54 | * These methods are the only way to get hold of a writeable block. | |
55 | */ | |
56 | ||
57 | /* | |
58 | * dm_tm_new_block() is pretty self-explanatory. Make sure you do actually | |
59 | * write to the whole of @data before you unlock, otherwise you could get | |
60 | * a data leak. (The other option is for tm_new_block() to zero new blocks | |
61 | * before handing them out, which will be redundant in most, if not all, | |
62 | * cases). | |
63 | * Zeroes the new block and returns with write lock held. | |
64 | */ | |
65 | int dm_tm_new_block(struct dm_transaction_manager *tm, | |
66 | struct dm_block_validator *v, | |
67 | struct dm_block **result); | |
68 | ||
69 | /* | |
70 | * dm_tm_shadow_block() allocates a new block and copies the data from @orig | |
71 | * to it. It then decrements the reference count on original block. Use | |
72 | * this to update the contents of a block in a data structure, don't | |
73 | * confuse this with a clone - you shouldn't access the orig block after | |
74 | * this operation. Because the tm knows the scope of the transaction it | |
75 | * can optimise requests for a shadow of a shadow to a no-op. Don't forget | |
76 | * to unlock when you've finished with the shadow. | |
77 | * | |
78 | * The @inc_children flag is used to tell the caller whether it needs to | |
79 | * adjust reference counts for children. (Data in the block may refer to | |
80 | * other blocks.) | |
81 | * | |
82 | * Shadowing implicitly drops a reference on @orig so you must not have | |
83 | * it locked when you call this. | |
84 | */ | |
85 | int dm_tm_shadow_block(struct dm_transaction_manager *tm, dm_block_t orig, | |
86 | struct dm_block_validator *v, | |
87 | struct dm_block **result, int *inc_children); | |
88 | ||
89 | /* | |
90 | * Read access. You can lock any block you want. If there's a write lock | |
91 | * on it outstanding then it'll block. | |
92 | */ | |
93 | int dm_tm_read_lock(struct dm_transaction_manager *tm, dm_block_t b, | |
94 | struct dm_block_validator *v, | |
95 | struct dm_block **result); | |
96 | ||
4c7da06f | 97 | void dm_tm_unlock(struct dm_transaction_manager *tm, struct dm_block *b); |
3241b1d3 JT |
98 | |
99 | /* | |
100 | * Functions for altering the reference count of a block directly. | |
101 | */ | |
102 | void dm_tm_inc(struct dm_transaction_manager *tm, dm_block_t b); | |
103 | ||
104 | void dm_tm_dec(struct dm_transaction_manager *tm, dm_block_t b); | |
105 | ||
106 | int dm_tm_ref(struct dm_transaction_manager *tm, dm_block_t b, | |
107 | uint32_t *result); | |
108 | ||
109 | struct dm_block_manager *dm_tm_get_bm(struct dm_transaction_manager *tm); | |
110 | ||
4646015d JT |
111 | /* |
112 | * If you're using a non-blocking clone the tm will build up a list of | |
113 | * requested blocks that weren't in core. This call will request those | |
114 | * blocks to be prefetched. | |
115 | */ | |
116 | void dm_tm_issue_prefetches(struct dm_transaction_manager *tm); | |
117 | ||
3241b1d3 JT |
118 | /* |
119 | * A little utility that ties the knot by producing a transaction manager | |
120 | * that has a space map managed by the transaction manager... | |
121 | * | |
122 | * Returns a tm that has an open transaction to write the new disk sm. | |
123 | * Caller should store the new sm root and commit. | |
384ef0e6 JT |
124 | * |
125 | * The superblock location is passed so the metadata space map knows it | |
126 | * shouldn't be used. | |
3241b1d3 JT |
127 | */ |
128 | int dm_tm_create_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, | |
3241b1d3 | 129 | struct dm_transaction_manager **tm, |
384ef0e6 | 130 | struct dm_space_map **sm); |
3241b1d3 JT |
131 | |
132 | int dm_tm_open_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, | |
384ef0e6 | 133 | void *sm_root, size_t root_len, |
3241b1d3 | 134 | struct dm_transaction_manager **tm, |
384ef0e6 | 135 | struct dm_space_map **sm); |
3241b1d3 JT |
136 | |
137 | #endif /* _LINUX_DM_TRANSACTION_MANAGER_H */ |