include/git2/sys/mempack.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_mempack_h__
   8 #define INCLUDE_sys_git_odb_mempack_h__
   9
  10 #include "git2/common.h"
  11 #include "git2/types.h"
  12 #include "git2/oid.h"
  13 #include "git2/odb.h"
  14 #include "git2/buffer.h"
  15
  16 /**
  17  * @file git2/sys/mempack.h
  18  * @brief Custom ODB backend that permits packing objects in-memory
  19  * @defgroup git_backend Git custom backend APIs
  20  * @ingroup Git
  21  * @{
  22  */
  23 GIT_BEGIN_DECL
  24
  25 /**
  26  * Instantiate a new mempack backend.
  27  *
  28  * The backend must be added to an existing ODB with the highest
  29  * priority.
  30  *
  31  *     git_mempack_new(&mempacker);
  32  *     git_repository_odb(&odb, repository);
  33  *     git_odb_add_backend(odb, mempacker, 999);
  34  *
  35  * Once the backend has been loaded, all writes to the ODB will
  36  * instead be queued in memory, and can be finalized with
  37  * `git_mempack_dump`.
  38  *
  39  * Subsequent reads will also be served from the in-memory store
  40  * to ensure consistency, until the memory store is dumped.
  41  *
  42  * @param out Pointer where to store the ODB backend
  43  * @return 0 on success; error code otherwise
  44  */
  45 GIT_EXTERN(int) git_mempack_new(git_odb_backend **out);
  46
  47 /**
  48  * Dump all the queued in-memory writes to a packfile.
  49  *
  50  * The contents of the packfile will be stored in the given buffer.
  51  * It is the caller's responsibility to ensure that the generated
  52  * packfile is available to the repository (e.g. by writing it
  53  * to disk, or doing something crazy like distributing it across
  54  * several copies of the repository over a network).
  55  *
  56  * Once the generated packfile is available to the repository,
  57  * call `git_mempack_reset` to cleanup the memory store.
  58  *
  59  * Calling `git_mempack_reset` before the packfile has been
  60  * written to disk will result in an inconsistent repository
  61  * (the objects in the memory store won't be accessible).
  62  *
  63  * @param pack Buffer where to store the raw packfile
  64  * @param repo The active repository where the backend is loaded
  65  * @param backend The mempack backend
  66  * @return 0 on success; error code otherwise
  67  */
  68 GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_backend *backend);
  69
  70 /**
  71  * Reset the memory packer by clearing all the queued objects.
  72  *
  73  * This assumes that `git_mempack_dump` has been called before to
  74  * store all the queued objects into a single packfile.
  75  *
  76  * Alternatively, call `reset` without a previous dump to "undo"
  77  * all the recently written objects, giving transaction-like
  78  * semantics to the Git repository.
  79  *
  80  * @param backend The mempack backend
  81  * @return 0 on success; error code otherwise
  82  */
  83 GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend);
  84
  85 GIT_END_DECL
  86
  87 #endif