Notes API: for_each_note(): Traverse the entire notes tree with a callback
This includes a first attempt at creating an optimal fanout scheme (which
is calculated on-the-fly, while traversing).
Signed-off-by: Johan Herland <johan@herland.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
diff --git a/notes.h b/notes.h
index 0041aec..2131912 100644
--- a/notes.h
+++ b/notes.h
@@ -35,6 +35,53 @@
*/
const unsigned char *get_note(const unsigned char *object_sha1);
+/*
+ * Flags controlling behaviour of for_each_note()
+ *
+ * Default behaviour of for_each_note() is to traverse every single note object
+ * in the notes tree, unpacking subtree entries along the way.
+ * The following flags can be used to alter the default behaviour:
+ *
+ * - DONT_UNPACK_SUBTREES causes for_each_note() NOT to unpack and recurse into
+ * subtree entries while traversing the notes tree. This causes notes within
+ * those subtrees NOT to be passed to the callback. Use this flag if you
+ * don't want to traverse _all_ notes, but only want to traverse the parts
+ * of the notes tree that have already been unpacked (this includes at least
+ * all notes that have been added/changed).
+ *
+ * - YIELD_SUBTREES causes any subtree entries that are encountered to be
+ * passed to the callback, before recursing into them. Subtree entries are
+ * not note objects, but represent intermediate directories in the notes
+ * tree. When passed to the callback, subtree entries will have a trailing
+ * slash in their path, which the callback may use to differentiate between
+ * note entries and subtree entries. Note that already-unpacked subtree
+ * entries are not part of the notes tree, and will therefore not be yielded.
+ * If this flag is used together with DONT_UNPACK_SUBTREES, for_each_note()
+ * will yield the subtree entry, but not recurse into it.
+ */
+#define FOR_EACH_NOTE_DONT_UNPACK_SUBTREES 1
+#define FOR_EACH_NOTE_YIELD_SUBTREES 2
+
+/*
+ * Invoke the specified callback function for each note
+ *
+ * If the callback returns nonzero, the note walk is aborted, and the return
+ * value from the callback is returned from for_each_note(). Hence, a zero
+ * return value from for_each_note() indicates that all notes were walked
+ * successfully.
+ *
+ * IMPORTANT: The callback function is NOT allowed to change the notes tree.
+ * In other words, the following functions can NOT be invoked (on the current
+ * notes tree) from within the callback:
+ * - add_note()
+ * - remove_note()
+ * - free_notes()
+ */
+typedef int each_note_fn(const unsigned char *object_sha1,
+ const unsigned char *note_sha1, char *note_path,
+ void *cb_data);
+int for_each_note(int flags, each_note_fn fn, void *cb_data);
+
/* Free (and de-initialize) the internal notes tree structure */
void free_notes(void);
