git2/sys/odb_backend.h

0001 /*
0002  * Copyright (C) the libgit2 contributors. All rights reserved.
0003  *
0004  * This file is part of libgit2, distributed under the GNU GPL v2 with
0005  * a Linking Exception. For full terms see the included COPYING file.
0006  */
0007 #ifndef INCLUDE_sys_git_odb_backend_h__
0008 #define INCLUDE_sys_git_odb_backend_h__
0009
0010 #include "git2/common.h"
0011 #include "git2/types.h"
0012 #include "git2/oid.h"
0013 #include "git2/odb.h"
0014
0015 /**
0016  * @file git2/sys/backend.h
0017  * @brief Git custom backend implementors functions
0018  * @defgroup git_backend Git custom backend APIs
0019  * @ingroup Git
0020  * @{
0021  */
0022 GIT_BEGIN_DECL
0023
0024 /**
0025  * An instance for a custom backend
0026  */
0027 struct git_odb_backend {
0028     unsigned int version;
0029     git_odb *odb;
0030
0031     /* read and read_prefix each return to libgit2 a buffer which
0032      * will be freed later. The buffer should be allocated using
0033      * the function git_odb_backend_data_alloc to ensure that libgit2
0034      * can safely free it later. */
0035     int GIT_CALLBACK(read)(
0036         void **, size_t *, git_object_t *, git_odb_backend *, const git_oid *);
0037
0038     /* To find a unique object given a prefix of its oid.  The oid given
0039      * must be so that the remaining (GIT_OID_SHA1_HEXSIZE - len)*4 bits are 0s.
0040      */
0041     int GIT_CALLBACK(read_prefix)(
0042         git_oid *, void **, size_t *, git_object_t *,
0043         git_odb_backend *, const git_oid *, size_t);
0044
0045     int GIT_CALLBACK(read_header)(
0046         size_t *, git_object_t *, git_odb_backend *, const git_oid *);
0047
0048     /**
0049      * Write an object into the backend. The id of the object has
0050      * already been calculated and is passed in.
0051      */
0052     int GIT_CALLBACK(write)(
0053         git_odb_backend *, const git_oid *, const void *, size_t, git_object_t);
0054
0055     int GIT_CALLBACK(writestream)(
0056         git_odb_stream **, git_odb_backend *, git_object_size_t, git_object_t);
0057
0058     int GIT_CALLBACK(readstream)(
0059         git_odb_stream **, size_t *, git_object_t *,
0060         git_odb_backend *, const git_oid *);
0061
0062     int GIT_CALLBACK(exists)(
0063         git_odb_backend *, const git_oid *);
0064
0065     int GIT_CALLBACK(exists_prefix)(
0066         git_oid *, git_odb_backend *, const git_oid *, size_t);
0067
0068     /**
0069      * If the backend implements a refreshing mechanism, it should be exposed
0070      * through this endpoint. Each call to `git_odb_refresh()` will invoke it.
0071      *
0072      * The odb layer will automatically call this when needed on failed
0073      * lookups (ie. `exists()`, `read()`, `read_header()`).
0074      */
0075     int GIT_CALLBACK(refresh)(git_odb_backend *);
0076
0077     int GIT_CALLBACK(foreach)(
0078         git_odb_backend *, git_odb_foreach_cb cb, void *payload);
0079
0080     int GIT_CALLBACK(writepack)(
0081         git_odb_writepack **, git_odb_backend *, git_odb *odb,
0082         git_indexer_progress_cb progress_cb, void *progress_payload);
0083
0084     /**
0085      * If the backend supports pack files, this will create a
0086      * `multi-pack-index` file which will contain an index of all objects
0087      * across all the `.pack` files.
0088      */
0089     int GIT_CALLBACK(writemidx)(git_odb_backend *);
0090
0091     /**
0092      * "Freshens" an already existing object, updating its last-used
0093      * time.  This occurs when `git_odb_write` was called, but the
0094      * object already existed (and will not be re-written).  The
0095      * underlying implementation may want to update last-used timestamps.
0096      *
0097      * If callers implement this, they should return `0` if the object
0098      * exists and was freshened, and non-zero otherwise.
0099      */
0100     int GIT_CALLBACK(freshen)(git_odb_backend *, const git_oid *);
0101
0102     /**
0103      * Frees any resources held by the odb (including the `git_odb_backend`
0104      * itself). An odb backend implementation must provide this function.
0105      */
0106     void GIT_CALLBACK(free)(git_odb_backend *);
0107 };
0108
0109 #define GIT_ODB_BACKEND_VERSION 1
0110 #define GIT_ODB_BACKEND_INIT {GIT_ODB_BACKEND_VERSION}
0111
0112 /**
0113  * Initializes a `git_odb_backend` with default values. Equivalent to
0114  * creating an instance with GIT_ODB_BACKEND_INIT.
0115  *
0116  * @param backend the `git_odb_backend` struct to initialize.
0117  * @param version Version the struct; pass `GIT_ODB_BACKEND_VERSION`
0118  * @return Zero on success; -1 on failure.
0119  */
0120 GIT_EXTERN(int) git_odb_init_backend(
0121     git_odb_backend *backend,
0122     unsigned int version);
0123
0124 /**
0125  * Allocate data for an ODB object.  Custom ODB backends may use this
0126  * to provide data back to the ODB from their read function.  This
0127  * memory should not be freed once it is returned to libgit2.  If a
0128  * custom ODB uses this function but encounters an error and does not
0129  * return this data to libgit2, then they should use the corresponding
0130  * git_odb_backend_data_free function.
0131  *
0132  * @param backend the ODB backend that is allocating this memory
0133  * @param len the number of bytes to allocate
0134  * @return the allocated buffer on success or NULL if out of memory
0135  */
0136 GIT_EXTERN(void *) git_odb_backend_data_alloc(git_odb_backend *backend, size_t len);
0137
0138 /**
0139  * Frees custom allocated ODB data.  This should only be called when
0140  * memory allocated using git_odb_backend_data_alloc is not returned
0141  * to libgit2 because the backend encountered an error in the read
0142  * function after allocation and did not return this data to libgit2.
0143  *
0144  * @param backend the ODB backend that is freeing this memory
0145  * @param data the buffer to free
0146  */
0147 GIT_EXTERN(void) git_odb_backend_data_free(git_odb_backend *backend, void *data);
0148
0149
0150 /*
0151  * Users can avoid deprecated functions by defining `GIT_DEPRECATE_HARD`.
0152  */
0153 #ifndef GIT_DEPRECATE_HARD
0154
0155 /**
0156  * Allocate memory for an ODB object from a custom backend.  This is
0157  * an alias of `git_odb_backend_data_alloc` and is preserved for
0158  * backward compatibility.
0159  *
0160  * This function is deprecated, but there is no plan to remove this
0161  * function at this time.
0162  *
0163  * @deprecated git_odb_backend_data_alloc
0164  * @see git_odb_backend_data_alloc
0165  */
0166 GIT_EXTERN(void *) git_odb_backend_malloc(git_odb_backend *backend, size_t len);
0167
0168 #endif
0169
0170 GIT_END_DECL
0171
0172 #endif