| 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 | /* |
| 13 | * This header defines the platform-agnostic interface that is to be |
| 14 | * implemented by the project to make it work on their respective supported |
| 15 | * systems, and to integrate it into the project itself. This header is not |
| 16 | * expected to be changed by the individual project. |
| 17 | */ |
| 18 | |
| 19 | #include "reftable-system.h" |
| 20 | |
| 21 | /* |
| 22 | * Return a random 32 bit integer. This function is expected to return |
| 23 | * pre-seeded data. |
| 24 | */ |
| 25 | uint32_t reftable_rand(void); |
| 26 | |
| 27 | /* |
| 28 | * An implementation-specific temporary file. By making this specific to the |
| 29 | * implementation it becomes possible to tie temporary files into any kind of |
| 30 | * signal or atexit handlers for cleanup on abnormal situations. |
| 31 | */ |
| 32 | struct reftable_tmpfile { |
| 33 | const char *path; |
| 34 | int fd; |
| 35 | void *priv; |
| 36 | }; |
| 37 | #define REFTABLE_TMPFILE_INIT ((struct reftable_tmpfile) { .fd = -1, }) |
| 38 | |
| 39 | /* |
| 40 | * Create a temporary file from a pattern similar to how mkstemp(3p) would. |
| 41 | * The `pattern` shall not be modified. On success, the structure at `out` has |
| 42 | * been initialized such that it is ready for use. Returns 0 on success, a |
| 43 | * reftable error code on error. |
| 44 | */ |
| 45 | int tmpfile_from_pattern(struct reftable_tmpfile *out, const char *pattern); |
| 46 | |
| 47 | /* |
| 48 | * Close the temporary file's file descriptor without removing the file itself. |
| 49 | * This is a no-op in case the file has already been closed beforehand. Returns |
| 50 | * 0 on success, a reftable error code on error. |
| 51 | */ |
| 52 | int tmpfile_close(struct reftable_tmpfile *t); |
| 53 | |
| 54 | /* |
| 55 | * Close the temporary file and delete it. This is a no-op in case the file has |
| 56 | * already been deleted or renamed beforehand. Returns 0 on success, a reftable |
| 57 | * error code on error. |
| 58 | */ |
| 59 | int tmpfile_delete(struct reftable_tmpfile *t); |
| 60 | |
| 61 | /* |
| 62 | * Rename the temporary file to the provided path. The temporary file must be |
| 63 | * active. Return 0 on success, a reftable error code on error. Deactivates the |
| 64 | * temporary file. |
| 65 | */ |
| 66 | int tmpfile_rename(struct reftable_tmpfile *t, const char *path); |
| 67 | |
| 68 | /* |
| 69 | * An implementation-specific file lock. Same as with `reftable_tmpfile`, |
| 70 | * making this specific to the implementation makes it possible to tie this |
| 71 | * into signal or atexit handlers such that we know to clean up stale locks on |
| 72 | * abnormal exits. |
| 73 | */ |
| 74 | struct reftable_flock { |
| 75 | const char *path; |
| 76 | int fd; |
| 77 | void *priv; |
| 78 | }; |
| 79 | #define REFTABLE_FLOCK_INIT ((struct reftable_flock){ .fd = -1, }) |
| 80 | |
| 81 | /* |
| 82 | * Acquire the lock for the given target path by exclusively creating a file |
| 83 | * with ".lock" appended to it. If that lock exists, we wait up to `timeout_ms` |
| 84 | * to acquire the lock. If `timeout_ms` is 0 we don't wait, if it is negative |
| 85 | * we block indefinitely. |
| 86 | * |
| 87 | * Return 0 on success, a reftable error code on error. Specifically, |
| 88 | * `REFTABLE_LOCK_ERROR` should be returned in case the target path is already |
| 89 | * locked. |
| 90 | */ |
| 91 | int flock_acquire(struct reftable_flock *l, const char *target_path, |
| 92 | long timeout_ms); |
| 93 | |
| 94 | /* |
| 95 | * Close the lockfile's file descriptor without removing the lock itself. This |
| 96 | * is a no-op in case the lockfile has already been closed beforehand. Returns |
| 97 | * 0 on success, a reftable error code on error. |
| 98 | */ |
| 99 | int flock_close(struct reftable_flock *l); |
| 100 | |
| 101 | /* |
| 102 | * Release the lock by unlinking the lockfile. This is a no-op in case the |
| 103 | * lockfile has already been released or committed beforehand. Returns 0 on |
| 104 | * success, a reftable error code on error. |
| 105 | */ |
| 106 | int flock_release(struct reftable_flock *l); |
| 107 | |
| 108 | /* |
| 109 | * Commit the lock by renaming the lockfile into place. Returns 0 on success, a |
| 110 | * reftable error code on error. |
| 111 | */ |
| 112 | int flock_commit(struct reftable_flock *l); |
| 113 | |
| 114 | /* Report the time in milliseconds. */ |
| 115 | uint64_t reftable_time_ms(void); |
| 116 | |
| 117 | struct reftable_mmap { |
| 118 | void *data; |
| 119 | size_t size; |
| 120 | void *priv; |
| 121 | }; |
| 122 | |
| 123 | /* |
| 124 | * Map the file into memory. Returns 0 on success, a reftable error code on |
| 125 | * error. |
| 126 | */ |
| 127 | int reftable_mmap(struct reftable_mmap *out, int fd, size_t len); |
| 128 | |
| 129 | /* |
| 130 | * Unmap the file from memory. Returns 0 on success, a reftable error code on |
| 131 | * error. |
| 132 | */ |
| 133 | int reftable_munmap(struct reftable_mmap *mmap); |
| 134 | |
| 135 | #endif |