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 * 41 * i) Make all changes for the transaction *except* for the superblock. 42 * Then call dm_tm_pre_commit() to flush them to disk. 43 * 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. 49 */ 50 int dm_tm_pre_commit(struct dm_transaction_manager *tm); 51 int dm_tm_commit(struct dm_transaction_manager *tm, struct dm_block *superblock); 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 97 void dm_tm_unlock(struct dm_transaction_manager *tm, struct dm_block *b); 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 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 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. 124 * 125 * The superblock location is passed so the metadata space map knows it 126 * shouldn't be used. 127 */ 128 int dm_tm_create_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, 129 struct dm_transaction_manager **tm, 130 struct dm_space_map **sm); 131 132 int dm_tm_open_with_sm(struct dm_block_manager *bm, dm_block_t sb_location, 133 void *sm_root, size_t root_len, 134 struct dm_transaction_manager **tm, 135 struct dm_space_map **sm); 136 137 #endif /* _LINUX_DM_TRANSACTION_MANAGER_H */