git2/sys/mempack.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_mempack_h__
0008 #define INCLUDE_sys_git_odb_mempack_h__
0009
0010 #include "git2/common.h"
0011 #include "git2/types.h"
0012 #include "git2/oid.h"
0013 #include "git2/odb.h"
0014 #include "git2/buffer.h"
0015
0016 /**
0017  * @file git2/sys/mempack.h
0018  * @brief Custom ODB backend that permits packing objects in-memory
0019  * @defgroup git_backend Git custom backend APIs
0020  * @ingroup Git
0021  * @{
0022  */
0023 GIT_BEGIN_DECL
0024
0025 /**
0026  * Instantiate a new mempack backend.
0027  *
0028  * The backend must be added to an existing ODB with the highest
0029  * priority.
0030  *
0031  *     git_mempack_new(&mempacker);
0032  *     git_repository_odb(&odb, repository);
0033  *     git_odb_add_backend(odb, mempacker, 999);
0034  *
0035  * Once the backend has been loaded, all writes to the ODB will
0036  * instead be queued in memory, and can be finalized with
0037  * `git_mempack_dump`.
0038  *
0039  * Subsequent reads will also be served from the in-memory store
0040  * to ensure consistency, until the memory store is dumped.
0041  *
0042  * @param out Pointer where to store the ODB backend
0043  * @return 0 on success; error code otherwise
0044  */
0045 GIT_EXTERN(int) git_mempack_new(git_odb_backend **out);
0046
0047 /**
0048  * Dump all the queued in-memory writes to a packfile.
0049  *
0050  * The contents of the packfile will be stored in the given buffer.
0051  * It is the caller's responsibility to ensure that the generated
0052  * packfile is available to the repository (e.g. by writing it
0053  * to disk, or doing something crazy like distributing it across
0054  * several copies of the repository over a network).
0055  *
0056  * Once the generated packfile is available to the repository,
0057  * call `git_mempack_reset` to cleanup the memory store.
0058  *
0059  * Calling `git_mempack_reset` before the packfile has been
0060  * written to disk will result in an inconsistent repository
0061  * (the objects in the memory store won't be accessible).
0062  *
0063  * @param pack Buffer where to store the raw packfile
0064  * @param repo The active repository where the backend is loaded
0065  * @param backend The mempack backend
0066  * @return 0 on success; error code otherwise
0067  */
0068 GIT_EXTERN(int) git_mempack_dump(git_buf *pack, git_repository *repo, git_odb_backend *backend);
0069
0070 /**
0071  * Reset the memory packer by clearing all the queued objects.
0072  *
0073  * This assumes that `git_mempack_dump` has been called before to
0074  * store all the queued objects into a single packfile.
0075  *
0076  * Alternatively, call `reset` without a previous dump to "undo"
0077  * all the recently written objects, giving transaction-like
0078  * semantics to the Git repository.
0079  *
0080  * @param backend The mempack backend
0081  * @return 0 on success; error code otherwise
0082  */
0083 GIT_EXTERN(int) git_mempack_reset(git_odb_backend *backend);
0084
0085 GIT_END_DECL
0086
0087 #endif