A monitor for detecting changes to a set of files. It can be used to efficiently test if any of a set of files (specified individually or by glob patterns) has changed since some snapshot. In addition, it also checks for changes in a value (of type a), and when there are no changes in either it returns a saved value (of type b).

The main use case looks like this: suppose we have some expensive action that depends on certain pure inputs and reads some set of files, and produces some pure result. We want to avoid re-running this action when it would produce the same result. So we need to monitor the files the action looked at, the other pure input values, and we need to cache the result. Then at some later point, if the input value didn't change, and none of the files changed, then we can re-use the cached result rather than re-running the action.

This can be achieved using a FileMonitor. Each FileMonitor instance saves state in a disk file, so the file for that has to be specified, making sure it is unique. The pattern is to use checkFileMonitorChanged to see if there's been any change. If there is, re-run the action, keeping track of the files, then use updateFileMonitor to record the current set of files to monitor, the current input value for the action, and the result of the action.

The typical occurrence of this pattern is captured by rerunIfChanged and the Rebuild monad. More complicated cases may need to use checkFileMonitorChanged and updateFileMonitor directly.

Define a new file monitor.

It's best practice to define file monitor values once, and then use the same value for checkFileMonitorChanged and updateFileMonitor as this ensures you get the same types a and b for reading and writing.

The path of the file monitor itself must be unique because it keeps state on disk and these would clash.

The result of checkFileMonitorChanged: either the monitored files or value changed (and it tells us which it was) or nothing changed and we get the cached result.

What kind of change checkFileMonitorChanged detected.

Test if the input value or files monitored by the FileMonitor have changed. If not, return the cached value.

See FileMonitor for a full explanation.

Update the input value and the set of files monitored by the FileMonitor, plus the cached value that may be returned in future.

This takes a snapshot of the state of the monitored files right now, so checkFileMonitorChanged will look for file system changes relative to this snapshot.

This is typically done once the action has been completed successfully and we have the action's result and we know what files it looked at. See FileMonitor for a full explanation.

If we do take the snapshot after the action has completed then we have a problem. The problem is that files might have changed while the action was running but after the action read them. If we take the snapshot after the action completes then we will miss these changes. The solution is to record a timestamp before beginning execution of the action and then we make the conservative assumption that any file that has changed since then has already changed, ie the file monitor state for these files will be such that checkFileMonitorChanged will report that they have changed.

So if you do use updateFileMonitor after the action (so you can discover the files used rather than predicting them in advance) then use beginUpdateFileMonitor to get a timestamp and pass that. Alternatively, if you take the snapshot in advance of the action, or you're not monitoring any files then you can use Nothing for the timestamp parameter.

A timestamp to help with the problem of file changes during actions. See updateFileMonitor for details.

Record a timestamp at the beginning of an action, and when the action completes call updateFileMonitor passing it the timestamp. See updateFileMonitor for details.

The state necessary to determine whether a set of monitored files has changed. It consists of two parts: a set of specific files to be monitored (index by their path), and a list of globs, which monitor may files at once.

The state necessary to determine whether a monitored file has changed.

This covers all the cases of MonitorFilePath except for globs which is covered separately by MonitorStateGlob.

The Maybe ModTime is to cover the case where we already consider the file to have changed, either because it had already changed by the time we did the snapshot (i.e. too new, changed since start of update process) or it no longer exists at all.

The state necessary to determine whether the files matched by a globbing match have changed.