Commit 7a3764bee92456e5ee2ed41be9abb0ffb4165eb7
2013-08-17T01:55:52
odb: document git_odb_stream Clarify the role of each function and in particular mention that there is no need for the backend or stream to worry about the object's id, as it will be given when `finalize_write` is called.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
diff --git a/include/git2/odb_backend.h b/include/git2/odb_backend.h
index 5696ee0..dca4995 100644
--- a/include/git2/odb_backend.h
+++ b/include/git2/odb_backend.h
@@ -67,15 +67,39 @@ typedef enum {
typedef struct git_hash_ctx git_hash_ctx;
-/** A stream to read/write from a backend */
+/**
+ * A stream to read/write from a backend.
+ *
+ * This represents a stream of data being written to or read from a
+ * backend. When writing, the frontend functions take care of
+ * calculating the object's id and all `finalize_write` needs to do is
+ * store the object with the id it is passed.
+ */
struct git_odb_stream {
git_odb_backend *backend;
unsigned int mode;
git_hash_ctx *hash_ctx;
+ /**
+ * Write at most `len` bytes into `buffer` and advance the
+ * stream.
+ */
int (*read)(git_odb_stream *stream, char *buffer, size_t len);
+
+ /**
+ * Write `len` bytes from `buffer` into the stream.
+ */
int (*write)(git_odb_stream *stream, const char *buffer, size_t len);
+
+ /**
+ * Store the contents of the stream as an object with the id
+ * specified in `oid`.
+ */
int (*finalize_write)(git_odb_stream *stream, const git_oid *oid);
+
+ /**
+ * Free the stream's memory.
+ */
void (*free)(git_odb_stream *stream);
};
diff --git a/include/git2/sys/odb_backend.h b/include/git2/sys/odb_backend.h
index 2d06613..31ffe1c 100644
--- a/include/git2/sys/odb_backend.h
+++ b/include/git2/sys/odb_backend.h
@@ -48,6 +48,10 @@ struct git_odb_backend {
int (* read_header)(
size_t *, git_otype *, git_odb_backend *, const git_oid *);
+ /**
+ * Write an object into the backend. The id of the object has
+ * already been calculated and is passed in.
+ */
int (* write)(
git_odb_backend *, const git_oid *, const void *, size_t, git_otype);