sentix

A cross-platform file watcher for Elixir based on fswatch.

Monthly Downloads: 16

Programming language: Elixir

License: MIT License

Tags: Files And Directories    

Latest version: v1.0.3

README

Sentix

Sentix is a file system watcher based on fswatch. It provides a stable port binding around fswatch (with configurable arguments) and translates the output to messages that are easy to work with from inside Elixir. Naturally, it goes without saying that you need fswatch installed to use this tool properly.

Installation

Sentix is available in Hex so you can install it pretty easily:

1. Add sentix to your list of dependencies in mix.exs:

   def deps do
     [{:sentix, "~> 1.0"}]
   end
   

2. Ensure sentix is started before your application:

   def application do
     [applications: [:sentix]]
   end
   

As previously mentioned, installing fswatch is a pre-req for using Sentix.

Usage

Startup

It's likely that you'll want to setup Sentix inside a Supervisor to ensure fault-tolerance. This can be done as follows:

Supervisor.start_link(
  [ worker(Sentix, [ :watcher_name, [ "/path/to/watch" ] ]) ]
)

Of course you can also start it manually using Sentix.start_link(:watcher_name, [ "/path/to/watch" ]).

The first two arguments to Sentix.start_link/3 are a name for the Sentix watcher and a list of paths to watch (or a single path, whichever). The third parameter is a list of options which are passed through the fswatch port. Please see the documentation for Sentix.start_link/3 for a full list of options which can be used.

Subscribing

Once you have a Sentix watcher running, you can subscribe processes to it to receive the forwarded notifications through the port. This is done using Sentix.subscribe/2:

Sentix.subscribe(:watcher_name)          # subscribes the calling process
Sentix.subscribe(:watcher_name, :sub)    # subscribe by a process name
Sentix.subscribe(:watcher_name, self())  # subscribe using a pid

A watcher can have any number of subscribers, but remember that more subscribers will result in a longer latency to pickup changes - so it may be that you need to implement grouping if you have a large number of subscribers.

In the case that a subscribed process is not alive when a message comes in, it will be removed from the watcher subscription list to avoid repeatedly sending messages that will never be received. In addition, an ETS cache is used to persist subscribers across restarts in case the watcher has to restart for any reason - so you don't need to subscribe again if the watcher dies (although you can do so just to be certain, watchers do not store duplicates).

Receiving Notifications

Once subscribed, you'll receive messages of the following format:

{ os_process_pid, { :fswatch, :file_event }, { file_path, event_list } }

The file path is naturally the path of the file which has been affected by a filesystem event. The list of events contains the events passed through by fswatch. Please note that these events are modified to atoms instead of the raw names from fswatch. For example, the IsFile event becomes :is_file in Sentix.

This message format is inspired by that of the fs library to make it possible for developers to migrate between the two projects easily.

Contributions

The Sentix API is deliberately tiny, as we leverage fswatch to do most of the work. If you have any feature requests, please make sure that it can be supported via the current fswatch API, or can easily be implemented (with low cost) on top of the API. Aside from this, please feel free to file an issue if you feel that something can be improved.

If you file any PRs, you can use the commands below to verify the test coverage of your changes, and the quality of your code (as measured by Credo).

$ mix test
$ mix credo
$ mix coveralls