reftable/system.h

   1 /*
   2 Copyright 2020 Google LLC
   3
   4 Use of this source code is governed by a BSD-style
   5 license that can be found in the LICENSE file or at
   6 https://developers.google.com/open-source/licenses/bsd
   7 */
   8
   9 #ifndef SYSTEM_H
  10 #define SYSTEM_H
  11
  12 /* This header glues the reftable library to the rest of Git */
  13
  14 #include "git-compat-util.h"
  15
  16 /*
  17  * An implementation-specific temporary file. By making this specific to the
  18  * implementation it becomes possible to tie temporary files into any kind of
  19  * signal or atexit handlers for cleanup on abnormal situations.
  20  */
  21 struct reftable_tmpfile {
  22         const char *path;
  23         int fd;
  24         void *priv;
  25 };
  26 #define REFTABLE_TMPFILE_INIT ((struct reftable_tmpfile) { .fd = -1, })
  27
  28 /*
  29  * Create a temporary file from a pattern similar to how mkstemp(3p) would.
  30  * The `pattern` shall not be modified. On success, the structure at `out` has
  31  * been initialized such that it is ready for use. Returns 0 on success, a
  32  * reftable error code on error.
  33  */
  34 int tmpfile_from_pattern(struct reftable_tmpfile *out, const char *pattern);
  35
  36 /*
  37  * Close the temporary file's file descriptor without removing the file itself.
  38  * This is a no-op in case the file has already been closed beforehand. Returns
  39  * 0 on success, a reftable error code on error.
  40  */
  41 int tmpfile_close(struct reftable_tmpfile *t);
  42
  43 /*
  44  * Close the temporary file and delete it. This is a no-op in case the file has
  45  * already been deleted or renamed beforehand. Returns 0 on success, a reftable
  46  * error code on error.
  47  */
  48 int tmpfile_delete(struct reftable_tmpfile *t);
  49
  50 /*
  51  * Rename the temporary file to the provided path. The temporary file must be
  52  * active. Return 0 on success, a reftable error code on error. Deactivates the
  53  * temporary file.
  54  */
  55 int tmpfile_rename(struct reftable_tmpfile *t, const char *path);
  56
  57 /*
  58  * An implementation-specific file lock. Same as with `reftable_tmpfile`,
  59  * making this specific to the implementation makes it possible to tie this
  60  * into signal or atexit handlers such that we know to clean up stale locks on
  61  * abnormal exits.
  62  */
  63 struct reftable_flock {
  64         const char *path;
  65         int fd;
  66         void *priv;
  67 };
  68 #define REFTABLE_FLOCK_INIT ((struct reftable_flock){ .fd = -1, })
  69
  70 /*
  71  * Acquire the lock for the given target path by exclusively creating a file
  72  * with ".lock" appended to it. If that lock exists, we wait up to `timeout_ms`
  73  * to acquire the lock. If `timeout_ms` is 0 we don't wait, if it is negative
  74  * we block indefinitely.
  75  *
  76  * Retrun 0 on success, a reftable error code on error.
  77  */
  78 int flock_acquire(struct reftable_flock *l, const char *target_path,
  79                   long timeout_ms);
  80
  81 /*
  82  * Close the lockfile's file descriptor without removing the lock itself. This
  83  * is a no-op in case the lockfile has already been closed beforehand. Returns
  84  * 0 on success, a reftable error code on error.
  85  */
  86 int flock_close(struct reftable_flock *l);
  87
  88 /*
  89  * Release the lock by unlinking the lockfile. This is a no-op in case the
  90  * lockfile has already been released or committed beforehand. Returns 0 on
  91  * success, a reftable error code on error.
  92  */
  93 int flock_release(struct reftable_flock *l);
  94
  95 /*
  96  * Commit the lock by renaming the lockfile into place. Returns 0 on success, a
  97  * reftable error code on error.
  98  */
  99 int flock_commit(struct reftable_flock *l);
 100
 101 #endif