System.FSNotify

This library does not currently report changes made to directories, only files within watched directories.

Minimal example:

{-# LANGUAGE OverloadedStrings #-} -- for FilePath literals

import System.FSNotify
import Control.Concurrent (threadDelay)
import Control.Monad (forever)

main =
  withManager $ \mgr -> do
    -- start a watching job (in the background)
    watchDir
      mgr          -- manager
      "."          -- directory to watch
      (const True) -- predicate
      print        -- action

    -- sleep forever (until interrupted)
    forever $ threadDelay 1000000

Events

data Event

A file event reported by a file watcher. Each event contains the canonical path for the file and a timestamp guaranteed to be after the event occurred (timestamps represent current time when FSEvents receives it from the OS and/or platform-specific Haskell modules).

Constructors

Added

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory

Modified

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory

ModifiedAttributes

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory

Removed

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory

WatchedDirectoryRemoved

Note: Linux-only

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory

CloseWrite

Note: Linux-only

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory

Unknown

Note: Linux-only

Fields

• eventPath :: FilePath
• eventTime :: UTCTime
• eventIsDirectory :: EventIsDirectory
• eventString :: String

Instances

Show Event

Defined in System.FSNotify.Types

Methods

showsPrec :: Int -> Event -> ShowS

show :: Event -> String

showList :: [Event] -> ShowS

Eq Event

Defined in System.FSNotify.Types

Methods

(==) :: Event -> Event -> Bool

(/=) :: Event -> Event -> Bool

data EventIsDirectory

Constructors

IsFile

IsDirectory

Instances

Show EventIsDirectory

Defined in System.FSNotify.Types

Methods

showsPrec :: Int -> EventIsDirectory -> ShowS

show :: EventIsDirectory -> String

showList :: [EventIsDirectory] -> ShowS

Eq EventIsDirectory

Defined in System.FSNotify.Types

Methods

(==) :: EventIsDirectory -> EventIsDirectory -> Bool

(/=) :: EventIsDirectory -> EventIsDirectory -> Bool

type EventChannel = Chan Event

type Action = Event -> IO ()

An action to be performed in response to an event.

type ActionPredicate = Event -> Bool

A predicate used to determine whether to act on an event.

Starting/Stopping

data WatchManager

Watch manager. You need one in order to create watching jobs.

withManager :: (WatchManager -> IO a) -> IO a

Perform an IO action with a WatchManager in place. Tear down the WatchManager after the action is complete.

startManager :: IO WatchManager

Start a file watch manager. Directories can only be watched when they are managed by a started watch manager. When finished watching. you must release resources via stopManager. It is preferrable if possible to use withManager to handle this automatically.

stopManager :: WatchManager -> IO ()

Stop a file watch manager. Stopping a watch manager will immediately stop watching for files and free resources.

Configuration

defaultConfig :: WatchConfig

Default configuration

• Uses OS watch mode and single thread.

data WatchConfig

Watch configuration.

confWatchMode :: WatchConfig -> WatchMode

Watch mode to use.

confThreadingMode :: WatchConfig -> ThreadingMode

Threading mode to use.

confOnHandlerException :: WatchConfig -> SomeException -> IO ()

Called when a handler throws an exception.

data WatchMode

Method of watching for changes.

Constructors

WatchModePoll

Detect changes by polling the filesystem. Less efficient and may miss fast changes. Not recommended unless you're experiencing problems with WatchModeOS (or WatchModeOS is not supported on your platform).

Fields

• watchModePollInterval :: Int

WatchModeOS

Use OS-specific mechanisms to be notified of changes (inotify on Linux, FSEvents on OSX, etc.). Not currently available on *BSD.

data ThreadingMode

Constructors

SingleThread

Use a single thread for the entire Manager. Event handler callbacks will run sequentially.

ThreadPerWatch

Use a single thread for each watch (i.e. each call to watchDir, watchTree, etc.). Callbacks within a watch will run sequentially but callbacks from different watches may be interleaved.

ThreadPerEvent

Launch a separate thread for every event handler.

Lower level

withManagerConf :: WatchConfig -> (WatchManager -> IO a) -> IO a

Like withManager, but configurable.

startManagerConf :: WatchConfig -> IO WatchManager

Like startManager, but configurable.

type StopListening = IO ()

An action that cancels a watching/listening job.

Watching

watchDir :: WatchManager -> FilePath -> ActionPredicate -> Action -> IO StopListening

Watch the immediate contents of a directory by committing an Action for each event. Watching the immediate contents of a directory will only report events associated with files within the specified directory, and not files within its subdirectories.

watchDirChan :: WatchManager -> FilePath -> ActionPredicate -> EventChannel -> IO StopListening

Watch the immediate contents of a directory by streaming events to a Chan. Watching the immediate contents of a directory will only report events associated with files within the specified directory, and not files within its subdirectories.

watchTree :: WatchManager -> FilePath -> ActionPredicate -> Action -> IO StopListening

Watch all the contents of a directory by committing an Action for each event. Watching all the contents of a directory will report events associated with files within the specified directory and its subdirectories.

watchTreeChan :: WatchManager -> FilePath -> ActionPredicate -> EventChannel -> IO StopListening

Watch all the contents of a directory by streaming events to a Chan. Watching all the contents of a directory will report events associated with files within the specified directory and its subdirectories.