Add more source code documentation.
[dss.git] / snap.h
1
2 /** The state of snapshot creation. */
3 enum {
4 /** We are ready to take the next snapshot. */
5 SCS_READY,
6 /** The pre-creation hook has been started. */
7 SCS_PRE_HOOK_RUNNING,
8 /** The pre-creation hook exited successfully. */
9 SCS_PRE_HOOK_SUCCESS,
10 /** The rsync process is running. */
11 SCS_RSYNC_RUNNING,
12 /** The rsync process exited successfully. */
13 SCS_RSYNC_SUCCESS,
14 /** The post-create hook has been started. */
15 SCS_POST_HOOK_RUNNING,
16 };
17
18 /**
19 * The status of a snapshot.
20 *
21 * The snapshot directories come in four different flavours, depending
22 * on how the two staus flags are set. Examples:
23 *
24 * Complete, not being deleted: 1204565370-1204565371.Sun_Mar_02_2008_14_33-Sun_Mar_02_2008_14_43.
25 * Complete, being deleted: 1204565370-1204565371.being_deleted.
26 * Incomplete, not being deleted: 1204565370-incomplete.
27 * incomplete, being deleted: 1204565370-incomplete.being_deleted.
28 */
29 enum snapshot_status_flags {
30 /** The rsync process terminated successfully. */
31 SS_COMPLETE = 1,
32 /** The rm process is running to remove this snapshot. */
33 SS_BEING_DELETED = 2,
34 };
35
36 /** Desribes one snapshot */
37 struct snapshot {
38 /** The name of the directory, relative to the destination dir. */
39 char *name;
40 /** Seconds after the epoch when this snapshot was created. */
41 int64_t creation_time;
42 /**
43 * Seconds after the epoch when creation of this snapshot completed.
44 * Only meaningful if the SS_COMPLTE bit is set.
45 */
46 int64_t completion_time;
47 /** See \ref snapshot_status_flags. */
48 enum snapshot_status_flags flags;
49 /** The interval this snapshot belongs to. */
50 unsigned interval;
51 };
52
53 struct snapshot_list {
54 int64_t now;
55 unsigned num_snapshots;
56 unsigned array_size;
57 struct snapshot **snapshots;
58 /**
59 * Array of size num_intervals + 1
60 *
61 * It contains the number of snapshots in each interval. interval_count[num_intervals]
62 * is the number of snapshots which belong to any interval greater than num_intervals.
63 */
64 unsigned *interval_count;
65 };
66
67 /** Iterate over all snapshots in a snapshot list. */
68 #define FOR_EACH_SNAPSHOT(s, i, sl) \
69 for ((i) = 0; (i) < (sl)->num_snapshots && ((s) = (sl)->snapshots[(i)]); (i)++)
70
71 /** Iterate backwards over all snapshots in a snapshot list. */
72 #define FOR_EACH_SNAPSHOT_REVERSE(s, i, sl) \
73 for ((i) = (sl)->num_snapshots; (i) > 0 && ((s) = (sl)->snapshots[(i - 1)]); (i)--)
74
75
76 unsigned desired_number_of_snapshots(int interval_num, int num_intervals);
77 void get_snapshot_list(struct snapshot_list *sl, int unit_interval,
78 int num_intervals);
79 void free_snapshot_list(struct snapshot_list *sl);
80 __malloc char *incomplete_name(int64_t start);
81 __malloc char *being_deleted_name(struct snapshot *s);
82 int complete_name(int64_t start, int64_t end, char **result);
83 __malloc char *name_of_newest_complete_snapshot(struct snapshot_list *sl);
84
85 /**
86 * Get the oldest snapshot in a snapshot list.
87 */
88 _static_inline_ struct snapshot *get_oldest_snapshot(struct snapshot_list *sl)
89 {
90 if (!sl->num_snapshots)
91 return NULL;
92 return sl->snapshots[0];
93 }