fsmonitor--daemon.h

   1 #ifndef FSMONITOR_DAEMON_H
   2 #define FSMONITOR_DAEMON_H
   3
   4 #ifdef HAVE_FSMONITOR_DAEMON_BACKEND
   5
   6 #include "cache.h"
   7 #include "dir.h"
   8 #include "run-command.h"
   9 #include "simple-ipc.h"
  10 #include "thread-utils.h"
  11 #include "fsmonitor-path-utils.h"
  12
  13 struct fsmonitor_batch;
  14 struct fsmonitor_token_data;
  15
  16 /*
  17  * Create a new batch of path(s).  The returned batch is considered
  18  * private and not linked into the fsmonitor daemon state.  The caller
  19  * should fill this batch with one or more paths and then publish it.
  20  */
  21 struct fsmonitor_batch *fsmonitor_batch__new(void);
  22
  23 /*
  24  * Free the list of batches starting with this one.
  25  */
  26 void fsmonitor_batch__free_list(struct fsmonitor_batch *batch);
  27
  28 /*
  29  * Add this path to this batch of modified files.
  30  *
  31  * The batch should be private and NOT (yet) linked into the fsmonitor
  32  * daemon state and therefore not yet visible to worker threads and so
  33  * no locking is required.
  34  */
  35 void fsmonitor_batch__add_path(struct fsmonitor_batch *batch, const char *path);
  36
  37 struct fsm_listen_data; /* opaque platform-specific data for listener thread */
  38 struct fsm_health_data; /* opaque platform-specific data for health thread */
  39
  40 struct fsmonitor_daemon_state {
  41         pthread_t listener_thread;
  42         pthread_t health_thread;
  43         pthread_mutex_t main_lock;
  44
  45         struct strbuf path_worktree_watch;
  46         struct strbuf path_gitdir_watch;
  47         struct alias_info alias;
  48         int nr_paths_watching;
  49
  50         struct fsmonitor_token_data *current_token_data;
  51
  52         struct strbuf path_cookie_prefix;
  53         pthread_cond_t cookies_cond;
  54         int cookie_seq;
  55         struct hashmap cookies;
  56
  57         int listen_error_code;
  58         int health_error_code;
  59         struct fsm_listen_data *listen_data;
  60         struct fsm_health_data *health_data;
  61
  62         struct ipc_server_data *ipc_server_data;
  63         struct strbuf path_ipc;
  64
  65 };
  66
  67 /*
  68  * Pathname classifications.
  69  *
  70  * The daemon classifies the pathnames that it receives from file
  71  * system notification events into the following categories and uses
  72  * that to decide whether clients are told about them.  (And to watch
  73  * for file system synchronization events.)
  74  *
  75  * The daemon only collects and reports on the set of modified paths
  76  * within the working directory (proper).
  77  *
  78  * The client should only care about paths within the working
  79  * directory proper (inside the working directory and not ".git" nor
  80  * inside of ".git/").  That is, the client has read the index and is
  81  * asking for a list of any paths in the working directory that have
  82  * been modified since the last token.  The client does not care about
  83  * file system changes within the ".git/" directory (such as new loose
  84  * objects or packfiles).  So the client will only receive paths that
  85  * are classified as IS_WORKDIR_PATH.
  86  *
  87  * Note that ".git" is usually a directory and is therefore inside
  88  * the cone of the FS watch that we have on the working directory root,
  89  * so we will also get FS events for disk activity on and within ".git/"
  90  * that we need to respond to or filter from the client.
  91  *
  92  * But Git also allows ".git" to be a *file* that points to a GITDIR
  93  * outside of the working directory.  When this happens, we need to
  94  * create FS watches on both the working directory root *and* on the
  95  * (external) GITDIR root.  (The latter is required because we put
  96  * cookie files inside it and use them to sync with the FS event
  97  * stream.)
  98  *
  99  * Note that in the context of this discussion, I'm using "GITDIR"
 100  * to only mean an external GITDIR referenced by a ".git" file.
 101  *
 102  * The platform FS event backends will receive watch-specific
 103  * relative paths (except for those OS's that always emit absolute
 104  * paths).  We use the following enum and routines to classify each
 105  * path so that we know how to handle it.  There is a slight asymmetry
 106  * here because ".git/" is inside the working directory and the
 107  * (external) GITDIR is not, and therefore how we handle events may
 108  * vary slightly, so I have different enums for "IS...DOT_GIT..." and
 109  * "IS...GITDIR...".
 110  *
 111  * The daemon uses the IS_DOT_GIT and IS_GITDIR internally to mean the
 112  * exact ".git" file/directory or GITDIR directory.  If the daemon
 113  * receives a delete event for either of these paths, it will
 114  * automatically shutdown, for example.
 115  *
 116  * Note that the daemon DOES NOT explicitly watch nor special case the
 117  * index.  The daemon does not read the index nor have any internal
 118  * index-relative state, so there are no "IS...INDEX..." enum values.
 119  */
 120 enum fsmonitor_path_type {
 121         IS_WORKDIR_PATH = 0,
 122
 123         IS_DOT_GIT,
 124         IS_INSIDE_DOT_GIT,
 125         IS_INSIDE_DOT_GIT_WITH_COOKIE_PREFIX,
 126
 127         IS_GITDIR,
 128         IS_INSIDE_GITDIR,
 129         IS_INSIDE_GITDIR_WITH_COOKIE_PREFIX,
 130
 131         IS_OUTSIDE_CONE,
 132 };
 133
 134 /*
 135  * Classify a pathname relative to the root of the working directory.
 136  */
 137 enum fsmonitor_path_type fsmonitor_classify_path_workdir_relative(
 138         const char *relative_path);
 139
 140 /*
 141  * Classify a pathname relative to a <gitdir> that is external to the
 142  * worktree directory.
 143  */
 144 enum fsmonitor_path_type fsmonitor_classify_path_gitdir_relative(
 145         const char *relative_path);
 146
 147 /*
 148  * Classify an absolute pathname received from a filesystem event.
 149  */
 150 enum fsmonitor_path_type fsmonitor_classify_path_absolute(
 151         struct fsmonitor_daemon_state *state,
 152         const char *path);
 153
 154 /*
 155  * Prepend the this batch of path(s) onto the list of batches associated
 156  * with the current token.  This makes the batch visible to worker threads.
 157  *
 158  * The caller no longer owns the batch and must not free it.
 159  *
 160  * Wake up the client threads waiting on these cookies.
 161  */
 162 void fsmonitor_publish(struct fsmonitor_daemon_state *state,
 163                        struct fsmonitor_batch *batch,
 164                        const struct string_list *cookie_names);
 165
 166 /*
 167  * If the platform-specific layer loses sync with the filesystem,
 168  * it should call this to invalidate cached data and abort waiting
 169  * threads.
 170  */
 171 void fsmonitor_force_resync(struct fsmonitor_daemon_state *state);
 172
 173 #endif /* HAVE_FSMONITOR_DAEMON_BACKEND */
 174 #endif /* FSMONITOR_DAEMON_H */