include/git2/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_git_odb_backend_h__
0008 #define INCLUDE_git_odb_backend_h__
0009
0010 #include "common.h"
0011 #include "types.h"
0012 #include "indexer.h"
0013
0014 /**
0015  * @file git2/backend.h
0016  * @brief Git custom backend functions
0017  * @defgroup git_odb Git object database routines
0018  * @ingroup Git
0019  * @{
0020  */
0021 GIT_BEGIN_DECL
0022
0023 /*
0024  * Constructors for in-box ODB backends.
0025  */
0026
0027 /** Options for configuring a packfile object backend. */
0028 typedef struct {
0029     unsigned int version; /**< version for the struct */
0030
0031     /**
0032      * Type of object IDs to use for this object database, or
0033      * 0 for default (currently SHA1).
0034      */
0035     git_oid_t oid_type;
0036 } git_odb_backend_pack_options;
0037
0038 /* The current version of the diff options structure */
0039 #define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1
0040
0041 /* Stack initializer for odb pack backend options.  Alternatively use
0042  * `git_odb_backend_pack_options_init` programmatic initialization.
0043  */
0044 #define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \
0045     { GIT_ODB_BACKEND_PACK_OPTIONS_VERSION }
0046
0047 /**
0048  * Create a backend for the packfiles.
0049  *
0050  * @param out location to store the odb backend pointer
0051  * @param objects_dir the Git repository's objects directory
0052  *
0053  * @return 0 or an error code
0054  */
0055 #ifdef GIT_EXPERIMENTAL_SHA256
0056 GIT_EXTERN(int) git_odb_backend_pack(
0057     git_odb_backend **out,
0058     const char *objects_dir,
0059     const git_odb_backend_pack_options *opts);
0060 #else
0061 GIT_EXTERN(int) git_odb_backend_pack(
0062     git_odb_backend **out,
0063     const char *objects_dir);
0064 #endif
0065
0066 /**
0067  * Create a backend out of a single packfile
0068  *
0069  * This can be useful for inspecting the contents of a single
0070  * packfile.
0071  *
0072  * @param out location to store the odb backend pointer
0073  * @param index_file path to the packfile's .idx file
0074  *
0075  * @return 0 or an error code
0076  */
0077 #ifdef GIT_EXPERIMENTAL_SHA256
0078 GIT_EXTERN(int) git_odb_backend_one_pack(
0079     git_odb_backend **out,
0080     const char *index_file,
0081     const git_odb_backend_pack_options *opts);
0082 #else
0083 GIT_EXTERN(int) git_odb_backend_one_pack(
0084     git_odb_backend **out,
0085     const char *index_file);
0086 #endif
0087
0088 typedef enum {
0089     GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0)
0090 } git_odb_backend_loose_flag_t;
0091
0092 /** Options for configuring a loose object backend. */
0093 typedef struct {
0094     unsigned int version; /**< version for the struct */
0095
0096     /** A combination of the `git_odb_backend_loose_flag_t` types. */
0097     uint32_t flags;
0098
0099     /**
0100      * zlib compression level to use (0-9), where 1 is the fastest
0101      * at the expense of larger files, and 9 produces the best
0102      * compression at the expense of speed.  0 indicates that no
0103      * compression should be performed.  -1 is the default (currently
0104      * optimizing for speed).
0105      */
0106     int compression_level;
0107
0108     /** Permissions to use creating a directory or 0 for defaults */
0109     unsigned int dir_mode;
0110
0111     /** Permissions to use creating a file or 0 for defaults */
0112     unsigned int file_mode;
0113
0114     /**
0115      * Type of object IDs to use for this object database, or
0116      * 0 for default (currently SHA1).
0117      */
0118     git_oid_t oid_type;
0119 } git_odb_backend_loose_options;
0120
0121 /* The current version of the diff options structure */
0122 #define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1
0123
0124 /* Stack initializer for odb loose backend options.  Alternatively use
0125  * `git_odb_backend_loose_options_init` programmatic initialization.
0126  */
0127 #define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \
0128     { GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 }
0129
0130 /**
0131  * Create a backend for loose objects
0132  *
0133  * @param out location to store the odb backend pointer
0134  * @param objects_dir the Git repository's objects directory
0135  * @param opts options for the loose object backend or NULL
0136  *
0137  * @return 0 or an error code
0138  */
0139 #ifdef GIT_EXPERIMENTAL_SHA256
0140 GIT_EXTERN(int) git_odb_backend_loose(
0141     git_odb_backend **out,
0142     const char *objects_dir,
0143     git_odb_backend_loose_options *opts);
0144 #else
0145 GIT_EXTERN(int) git_odb_backend_loose(
0146     git_odb_backend **out,
0147     const char *objects_dir,
0148     int compression_level,
0149     int do_fsync,
0150     unsigned int dir_mode,
0151     unsigned int file_mode);
0152 #endif
0153
0154 /** Streaming mode */
0155 typedef enum {
0156     GIT_STREAM_RDONLY = (1 << 1),
0157     GIT_STREAM_WRONLY = (1 << 2),
0158     GIT_STREAM_RW = (GIT_STREAM_RDONLY | GIT_STREAM_WRONLY)
0159 } git_odb_stream_t;
0160
0161 /**
0162  * A stream to read/write from a backend.
0163  *
0164  * This represents a stream of data being written to or read from a
0165  * backend. When writing, the frontend functions take care of
0166  * calculating the object's id and all `finalize_write` needs to do is
0167  * store the object with the id it is passed.
0168  */
0169 struct git_odb_stream {
0170     git_odb_backend *backend;
0171     unsigned int mode;
0172     void *hash_ctx;
0173
0174 #ifdef GIT_EXPERIMENTAL_SHA256
0175     git_oid_t oid_type;
0176 #endif
0177
0178     git_object_size_t declared_size;
0179     git_object_size_t received_bytes;
0180
0181     /**
0182      * Write at most `len` bytes into `buffer` and advance the stream.
0183      */
0184     int GIT_CALLBACK(read)(git_odb_stream *stream, char *buffer, size_t len);
0185
0186     /**
0187      * Write `len` bytes from `buffer` into the stream.
0188      */
0189     int GIT_CALLBACK(write)(git_odb_stream *stream, const char *buffer, size_t len);
0190
0191     /**
0192      * Store the contents of the stream as an object with the id
0193      * specified in `oid`.
0194      *
0195      * This method might not be invoked if:
0196      * - an error occurs earlier with the `write` callback,
0197      * - the object referred to by `oid` already exists in any backend, or
0198      * - the final number of received bytes differs from the size declared
0199      *   with `git_odb_open_wstream()`
0200      */
0201     int GIT_CALLBACK(finalize_write)(git_odb_stream *stream, const git_oid *oid);
0202
0203     /**
0204      * Free the stream's memory.
0205      *
0206      * This method might be called without a call to `finalize_write` if
0207      * an error occurs or if the object is already present in the ODB.
0208      */
0209     void GIT_CALLBACK(free)(git_odb_stream *stream);
0210 };
0211
0212 /** A stream to write a pack file to the ODB */
0213 struct git_odb_writepack {
0214     git_odb_backend *backend;
0215
0216     int GIT_CALLBACK(append)(git_odb_writepack *writepack, const void *data, size_t size, git_indexer_progress *stats);
0217     int GIT_CALLBACK(commit)(git_odb_writepack *writepack, git_indexer_progress *stats);
0218     void GIT_CALLBACK(free)(git_odb_writepack *writepack);
0219 };
0220
0221 GIT_END_DECL
0222
0223 #endif