2-- Module : Streamly.FileSystem.Event
3-- Copyright : (c) 2020 Composewell Technologies
4-- License : BSD-3-Clause
5-- Maintainer : streamly@composewell.com
6-- Stability : pre-release
9-- File system event notification API portable across Linux, macOS and Windows
12-- Note that recursive directory tree watch does not work reliably on Linux
13-- (see notes in the Linux module), therefore, recursive watch API is not
14-- provided in this module. However, you can use it from the platform specific
17-- For platform specific APIs please see the following modules:
19-- * "Streamly.Internal.FileSystem.Event.Darwin"
20-- * "Streamly.Internal.FileSystem.Event.Linux"
21-- * "Streamly.Internal.FileSystem.Event.Windows"
23module Streamly.Internal.FileSystem.Event
34 -- ** Item CRUD events
40 -- ** Exception Conditions
48import Data.List.NonEmpty (NonEmpty)
49import Data.Word (Word8)
50import Streamly.Internal.Data.Array.Foreign (Array)
51import Streamly.Prelude (SerialT)
53#if defined(CABAL_OS_DARWIN)
54import Streamly.Internal.FileSystem.Event.Darwin (Event)
55import qualified Streamly.Internal.FileSystem.Event.Darwin as Event
56#elif defined(CABAL_OS_LINUX)
57import Streamly.Internal.FileSystem.Event.Linux (Event)
58import qualified Streamly.Internal.FileSystem.Event.Linux as Event
59#elif defined(CABAL_OS_WINDOWS)
60import Streamly.Internal.FileSystem.Event.Windows (Event)
61import qualified Streamly.Internal.FileSystem.Event.Windows as Event
63#error "FS Events not supported on this platform"
66-- XXX Ensure that defaultConfig is the same for all platforms.
68-- XXX Ensure that equivalent events are generated on all platforms when same
69-- operations are done. Document any differences in behavior on different
70-- platforms. Any events that are not common to all platforms should be
73-- XXX Only need to set common event types for macOS/Linux/Windows
74-- XXX write a test, that generates all types of events that can possibly
75-- occur on each platform. Then create a common test that only checks
76-- for the common subset of those.
78-------------------------------------------------------------------------------
80-------------------------------------------------------------------------------
82-- macOS and Windows seem to do a path level watch i.e. they watch the path
83-- rather than the underlying inode, possibly they can map the inode back to a
84-- path?. On Linux we cannot keep watching a watch root if the inode it is
85-- pointing to has moved. However, the inode continues to be watched in this
86-- case instead of the path, which is not the case for macOS.
88-- To make the behavior same for all platforms, for the Linux case we will have
89-- to stop watching the inode if it moves from under the path
90-- (setUnwatchMoved). And on macOS we can stop watching a path if the inode
91-- under it changes i.e. just filter out events for that path.
93-- Also, to make the behavior of Linux same as macOS we need to set
94-- setFollowSymLinks on Linux.
96-- XXX Verify all the cases mentioned below using test cases.
98-- | Start monitoring a list of file system paths for file system events. The
99-- paths could be files or directories. Monitoring starts from the current
100-- time onwards. The paths are specified as UTF-8 encoded 'Array' of 'Word8'.
102-- If a watch root is a symbolic link then the target of the link is watched.
103-- Fails if the watched path does not exist. If the user does not have
104-- permissions (specific permissions?) on the watch root then no events are
105-- generated. No events are generated if the watch root itself is renamed or
108-- This API watches for changes in the watch root directory only, any changes
109-- in the subdirectories of the watch root are not watched. However, on macOS
110-- the watch is always recursive, but do not rely on that behavior, it may
111-- change without notice in future. If you want to use recursive watch please
112-- use platform specific modules.
116watch :: NonEmpty (Array Word8) -> SerialT IO Event
117#if defined(CABAL_OS_DARWIN)
118watch = Event.watchRecursive
123-- | Like 'watch' except that if a watched path is a directory the whole
124-- directory tree under it is watched recursively.
126-- On Linux 'watchRecursive' may be more expensive than 'watch'.
130_watchRecursive :: NonEmpty (Array Word8) -> SerialT IO Event
131_watchRecursive = Event.watchRecursive
133-------------------------------------------------------------------------------
135-------------------------------------------------------------------------------
137-- XXX Ensure that on all paltforms the path has same conventions. That is do
138-- not have a trailing path separator on one platfrom and not on another.
140-- XXX We should use getRelPath instead so that the behavior when the root is a
141-- symlink becomes platform independent.
143-- | Get the absolute path of the file system object for which the event is
144-- generated. The path is a UTF-8 encoded array of bytes.
146-- When the watch root is a symlink the behavior is different on different
149-- * On Linux and Windows, the absolute path returned is via the original
152-- * On macOS the absolute path returned is via the real path of the root after
153-- resolving the symlink.
155-- This API is subject to removal in future, to be replaced by a platform
156-- independent @getRelPath@.
160getAbsPath :: Event -> Array Word8
161getAbsPath = Event.getAbsPath
163-- | Determine whether the event indicates creation of an object within the
164-- monitored path. This event is generated when any file system object is
167-- For hard links the behavior is different on different operating systems. On
168-- macOS hard linking does not generate a create event, it generates an
169-- 'isInodeAttrsChanged' event on the directory instead (see the Darwin
170-- module). On Linux and Windows hard linking generates a create event.
174isCreated :: Event -> Bool
175isCreated = Event.isCreated
177-- XXX To make the behavior consistent, can we block the event on watch root on
180-- | Determine whether the event indicates deletion of an object within the
181-- monitored path. On Linux and Windows hard link deletion generates a delete
184-- On Linux and Windows, this event does not occur when the watch root itself
185-- is deleted. On macOS it occurs on deleting the watch root when it is not a
188-- See also 'isRootDeleted' event for Linux.
192isDeleted :: Event -> Bool
193isDeleted = Event.isDeleted
195-- | Determine whether the event indicates rename of an object within the
196-- monitored path. This event is generated when an object is renamed within the
197-- watched directory or if it is moved out of or in the watched directory.
198-- Moving hard links is no different than other types of objects.
202isMoved :: Event -> Bool
203isMoved = Event.isMoved
205-- XXX Make the Windows behavior consistent with other platforms by removing
206-- the event from directories.
208-- | Determine whether the event indicates modification of an object within the
209-- monitored path. This event is generated on file modification on all
212-- On Linux and macOS this event is never generated for directories. On
213-- Windows (in recursive watch mode) this event is generated for directories as
214-- well when an object is created in or deleted from the directory.
218isModified :: Event -> Bool
219isModified = Event.isModified
221-- | An event that indicates that some events before this may have been lost,
222-- therefore, we need to take some recovery action.
226isEventsLost :: Event -> Bool
227isEventsLost = Event.isEventsLost
229-------------------------------------------------------------------------------
231-------------------------------------------------------------------------------
233-- | Convert an 'Event' record to a String representation. Note that the output
234-- of this function may be different on different platforms because it may
235-- contain platform specific details.
239showEvent :: Event -> String
240showEvent = Event.showEvent
keysesc to close
- j k
- move down, up
- enter
- open
- esc
- back, or up a level
- 1 2 3 4
- readme, files, commits, refs
- /
- filter
- y
- copy the clone command
- c
- compare the chosen commit with another (or shift-click both)
- ?
- show or hide this list