src/git_revwalk.h

   1 /*
   2  * All rights reserved.
   3  *
   4  * Redistribution and use in source and binary forms, with or
   5  * without modification, are permitted provided that the following
   6  * conditions are met:
   7  *
   8  * - Redistributions of source code must retain the above copyright
   9  *   notice, this list of conditions and the following disclaimer.
  10  *
  11  * - Redistributions in binary form must reproduce the above
  12  *   copyright notice, this list of conditions and the following
  13  *   disclaimer in the documentation and/or other materials provided
  14  *   with the distribution.
  15  *
  16  * - Neither the name of the Git Development Community nor the
  17  *   names of its contributors may be used to endorse or promote
  18  *   products derived from this software without specific prior
  19  *   written permission.
  20  *
  21  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
  22  * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
  23  * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  24  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  26  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  28  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  30  * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  31  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
  33  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  34  */
  35
  36 #ifndef INCLUDE_git_revwalk_h__
  37 #define INCLUDE_git_revwalk_h__
  38
  39 #include "git_common.h"
  40 #include "git_odb.h"
  41 #include "git_commit.h"
  42
  43 /**
  44  * @file git_revwalk.h
  45  * @brief Git revision traversal routines
  46  * @defgroup git_revwalk Git revision traversal routines
  47  * @ingroup Git
  48  * @{
  49  */
  50 GIT_BEGIN_DECL
  51
  52 /** Configuration of a revision pool. */
  53 typedef struct git_revp_attr git_revp_attr;
  54
  55 /**
  56  * Allocate an empty pool configuration.
  57  *
  58  * The resulting configuration is identical to passing NULL
  59  * to git_revp_alloc().
  60  *
  61  * @return a new configuration block.
  62  *         NULL if there is insufficient memory.
  63  */
  64 GIT_EXTERN(git_revp_attr*) git_revp_attr_alloc(void);
  65
  66 /**
  67  * Setup the application's per-commit data allocation.
  68  *
  69  * If size is non-zero the requested number of bytes is allocated
  70  * alongside every git_commit used by the revision pool, allowing
  71  * constant-time access to per-commit application data.
  72  *
  73  * If init is not NULL the function is invoked with the commit and
  74  * the application data pointer, allowing the function to populate
  75  * the application's data space the first time the commit is parsed
  76  * into the pool.  Space available within the application data is
  77  * not initialized.  Subsequent resets do not invoke this method.
  78  *
  79  * If init is NULL and size is non-zero the application data space
  80  * is cleared during the first parse.
  81  *
  82  * @param attr the pool configuration to adjust.
  83  * @param size number of bytes required by the application on
  84  *        each rev_commit instance within the pool.
  85  * @param init optional callback function to initialize the
  86  *        application data space.  If NULL the application
  87  *        space will be zeroed.  If supplied the application
  88  *        space may contain random garbage.
  89  */
  90 GIT_EXTERN(void) git_revp_attr_appdata(
  91         git_revp_attr *attr,
  92         size_t size,
  93         int (*init)(git_commit *, void *));
  94
  95 /**
  96  * Free a pool configuration.
  97  * @param attr the configuration to free.  No-op if NULL.
  98  */
  99 GIT_EXTERN(void) git_revp_attr_free(git_revp_attr *attr);
 100
 101 /**
 102  * Allocate a new revision traversal pool.
 103  *
 104  * The configuration is copied during allocation.  Changes
 105  * to the configuration after allocation do not affect the pool
 106  * returned by this function.  Callers may safely free the
 107  * passed configuration after the function completes.
 108  *
 109  * @param db the database objects are read from.
 110  * @param attr configuration for the pool.
 111  *        NULL to use a default configuration.
 112  * @return the new traversal handle; NULL if memory is exhausted.
 113  */
 114 GIT_EXTERN(git_revp*) git_revp_alloc(
 115         git_odb *db,
 116         const git_revp_attr *attr);
 117
 118 /**
 119  * Reset the traversal machinary for reuse.
 120  * @param pool traversal handle to reset.
 121  */
 122 GIT_EXTERN(void) git_revp_reset(git_revp *pool);
 123
 124 /**
 125  * Mark an object to start traversal from.
 126  * @param pool the pool being used for the traversal.
 127  * @param commit the commit the commit to start from.
 128  */
 129 GIT_EXTERN(void) git_revp_pushc(git_revp *pool, git_commit *commit);
 130
 131 /**
 132  * Mark a commit (and its ancestors) uninteresting for the output.
 133  * @param pool the pool being used for the traversal.
 134  * @param commit the commit the commit to start from.
 135  */
 136 GIT_EXTERN(void) git_revp_hidec(git_revp *pool, git_commit *commit);
 137
 138 /**
 139  * Get the next commit from the revision traversal.
 140  * @param pool the pool to pop the commit from.
 141  * @return next commit; NULL if there is no more output.
 142  */
 143 GIT_EXTERN(git_commit*) git_revp_nextc(git_revp *pool);
 144
 145 /**
 146  * Free a revwalk previously allocated.
 147  * @param pool traversal handle to close.  If NULL nothing occurs.
 148  */
 149 GIT_EXTERN(void) git_revp_free(git_revp *pool);
 150
 151 /** @} */
 152 GIT_END_DECL
 153 #endif