include/git2/sys/odb_backend.h

   1 /*
   2  * Copyright (C) the libgit2 contributors. All rights reserved.
   3  *
   4  * This file is part of libgit2, distributed under the GNU GPL v2 with
   5  * a Linking Exception. For full terms see the included COPYING file.
   6  */
   7 #ifndef INCLUDE_sys_git_odb_backend_h__
   8 #define INCLUDE_sys_git_odb_backend_h__
   9
  10 #include "git2/common.h"
  11 #include "git2/types.h"
  12 #include "git2/oid.h"
  13 #include "git2/odb.h"
  14
  15 /**
  16  * @file git2/sys/backend.h
  17  * @brief Git custom backend implementors functions
  18  * @defgroup git_backend Git custom backend APIs
  19  * @ingroup Git
  20  * @{
  21  */
  22 GIT_BEGIN_DECL
  23
  24 /**
  25  * An instance for a custom backend
  26  */
  27 struct git_odb_backend {
  28         unsigned int version;
  29         git_odb *odb;
  30
  31         /* read and read_prefix each return to libgit2 a buffer which
  32          * will be freed later. The buffer should be allocated using
  33          * the function git_odb_backend_data_alloc to ensure that libgit2
  34          * can safely free it later. */
  35         int GIT_CALLBACK(read)(
  36                 void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *);
  37
  38         /* To find a unique object given a prefix of its oid.  The oid given
  39          * must be so that the remaining (GIT_OID_HEXSZ - len)*4 bits are 0s.
  40          */
  41         int GIT_CALLBACK(read_prefix)(
  42                 git_oid *, void **, size_t *, git_object_t *,
  43                 git_odb_backend *, const git_oid *, size_t);
  44
  45         int GIT_CALLBACK(read_header)(
  46                 size_t *, git_object_t *, git_odb_backend *, const git_oid *);
  47
  48         /**
  49          * Write an object into the backend. The id of the object has
  50          * already been calculated and is passed in.
  51          */
  52         int GIT_CALLBACK(write)(
  53                 git_odb_backend *, const git_oid *, const void *, size_t, git_object_t);
  54
  55         int GIT_CALLBACK(writestream)(
  56                 git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t);
  57
  58         int GIT_CALLBACK(readstream)(
  59                 git_odb_stream **, size_t *, git_object_t *,
  60                 git_odb_backend *, const git_oid *);
  61
  62         int GIT_CALLBACK(exists)(
  63                 git_odb_backend *, const git_oid *);
  64
  65         int GIT_CALLBACK(exists_prefix)(
  66                 git_oid *, git_odb_backend *, const git_oid *, size_t);
  67
  68         /**
  69          * If the backend implements a refreshing mechanism, it should be exposed
  70          * through this endpoint. Each call to `git_odb_refresh()` will invoke it.
  71          *
  72          * However, the backend implementation should try to stay up-to-date as much
  73          * as possible by itself as libgit2 will not automatically invoke
  74          * `git_odb_refresh()`. For instance, a potential strategy for the backend
  75          * implementation to achieve this could be to internally invoke this
  76          * endpoint on failed lookups (ie. `exists()`, `read()`, `read_header()`).
  77          */
  78         int GIT_CALLBACK(refresh)(git_odb_backend *);
  79
  80         int GIT_CALLBACK(foreach)(
  81                 git_odb_backend *, git_odb_foreach_cb cb, void *payload);
  82
  83         int GIT_CALLBACK(writepack)(
  84                 git_odb_writepack **, git_odb_backend *, git_odb *odb,
  85                 git_indexer_progress_cb progress_cb, void *progress_payload);
  86
  87         /**
  88          * If the backend supports pack files, this will create a
  89          * `multi-pack-index` file which will contain an index of all objects
  90          * across all the `.pack` files.
  91          */
  92         int GIT_CALLBACK(writemidx)(git_odb_backend *);
  93
  94         /**
  95          * "Freshens" an already existing object, updating its last-used
  96          * time.  This occurs when `git_odb_write` was called, but the
  97          * object already existed (and will not be re-written).  The
  98          * underlying implementation may want to update last-used timestamps.
  99          *
 100          * If callers implement this, they should return `0` if the object
 101          * exists and was freshened, and non-zero otherwise.
 102          */
 103         int GIT_CALLBACK(freshen)(git_odb_backend *, const git_oid *);
 104
 105         /**
 106          * Frees any resources held by the odb (including the `git_odb_backend`
 107          * itself). An odb backend implementation must provide this function.
 108          */
 109         void GIT_CALLBACK(free)(git_odb_backend *);
 110 };
 111
 112 #define GIT_ODB_BACKEND_VERSION 1
 113 #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
 114
 115 /**
 116  * Initializes a `git_odb_backend` with default values. Equivalent to
 117  * creating an instance with GIT_ODB_BACKEND_INIT.
 118  *
 119  * @param backend the `git_odb_backend` struct to initialize.
 120  * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION`
 121  * @return Zero on success; -1 on failure.
 122  */
 123 GIT_EXTERN(int) git_odb_init_backend(
 124         git_odb_backend *backend,
 125         unsigned int version);
 126
 127 /**
 128  * Allocate data for an ODB object.  Custom ODB backends may use this
 129  * to provide data back to the ODB from their read function.  This
 130  * memory should not be freed once it is returned to libgit2.  If a
 131  * custom ODB uses this function but encounters an error and does not
 132  * return this data to libgit2, then they should use the corresponding
 133  * git_odb_backend_data_free function.
 134  *
 135  * @param backend the ODB backend that is allocating this memory
 136  * @param len the number of bytes to allocate
 137  * @return the allocated buffer on success or NULL if out of memory
 138  */
 139 GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len);
 140
 141 /**
 142  * Frees custom allocated ODB data.  This should only be called when
 143  * memory allocated using git_odb_backend_data_alloc is not returned
 144  * to libgit2 because the backend encountered an error in the read
 145  * function after allocation and did not return this data to libgit2.
 146  *
 147  * @param backend the ODB backend that is freeing this memory
 148  * @param data the buffer to free
 149  */
 150 GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data);
 151
 152
 153 /*
 154  * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`.
 155  */
 156 #ifndef GIT_DEPRECATE_HARD
 157
 158 /**
 159  * Allocate memory for an ODB object from a custom backend.  This is
 160  * an alias of `git_odb_backend_data_alloc` and is preserved for
 161  * backward compatibility.
 162  *
 163  * This function is deprecated, but there is no plan to remove this
 164  * function at this time.
 165  *
 166  * @deprecated git_odb_backend_data_alloc
 167  * @see git_odb_backend_data_alloc
 168  */
 169 GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len);
 170
 171 #endif
 172
 173 GIT_END_DECL
 174
 175 #endif