1
The new version of clear_holders is based around a data structure called a
2
holder_tree which represents the current storage hirearchy above a specified
3
starting device. Each node in a holders tree contains data about the node and a
4
key 'holders' which contains a list of all nodes that depend on it. The keys in
5
a holdres_tree node are:
6
- device: the path to the device in /sys/class/block
7
- dev_type: what type of storage layer the device is. possible values:
14
- name: the kname of the device (used for display)
15
- holders: holders_trees for devices depending on the current device
17
A holders tree can be generated for a device using the function
18
clear_holders.gen_holders_tree. The device can be specified either as a path in
19
/sys/class/block or as a path in /dev.
21
The new implementation of block.clear_holders shuts down storage devices in a
22
holders tree starting from the leaves of the tree and ascending towards the
23
root. The old implementation of clear_holders ascended up each path of the tree
24
separately, in a pattern similar to depth first search. The problem with the
25
old implementation is that in some cases either an attempt would be made to
26
remove one storage device while other devices depended on it or clear_holders
27
would attempt to shut down the same storage device several times. In order to
28
cope with this the old version of clear_holders had logic to handle expected
29
failures and hope for the best moving forward. The new version of clear_holders
30
is able to run without many anticipated failures.
32
The logic to plan what order to shut down storage layers in is in
33
clear_holders.plan_shutdown_holders_trees. This function accepts either a
34
single holders tree or a list of holders trees. When run with a list of holders
35
trees, it assumes that all of these trees start at basically the same layer in
36
the overall storage hirearcy for the system (i.e. a list of holders trees
37
starting from all of the target installation disks). This function returns a
38
list of dictionaries, with each dictionary containing the keys:
39
- device: the path to the device in /sys/class/block
40
- dev_type: what type of storage layer the device is. possible values:
47
- level: the level of the device in the current storage hirearchy
50
The items in the list returned by clear_holders.plan_shutdown_holders_trees
51
should be processed in order to make sure the holders trees are shutdown fully
53
The main interface for clear_holders is the function
54
clear_holders.clear_holders. If the system has just been booted it could be
55
beneficial to run the function clear_holders.start_clear_holders_deps before
56
using clear_holders.clear_holders. This ensures clear_holders will be able to
57
properly storage devices. The function clear_holders.clear_holders can be
58
passed either a single device or a list of devices and will shut down all
59
storage devices above the device(s). The devices can be specified either by
60
path in /dev or by path in /sys/class/block.
62
In order to test if a device or devices are free to be partitioned/formatted,
63
the function clear_holders.assert_clear can be passed either a single device or
64
a list of devices, with devices specified either by path in /dev or by path in
65
/sys/class/block. If there are any storage devices that depend on one of the
66
devices passed to clear_holders.assert_clear, then an OSError will be raised.
67
If clear_holders.assert_clear does not raise any errors, then the devices
68
specified should be ready for partitioning.
70
It is possible to query further information about storage devices using
73
Holders for a individual device can be queried using clear_holders.get_holders.
74
Results are returned as a list or knames for holding devices.
76
A holders tree can be printed in a human readable format using
77
clear_holders.format_holders_tree(). Example output:
added
removed
doc/devel/clear_holders_doc.txt
