Description
Provides coalesced filesystem-change hints through task-aware readiness. Notifications are advisory: callers must inspect the watched object to determine its current state and must not use events as an operation count.
Example:
Watcher.Open;
Id := Watcher.Add ("configuration");
Watcher.Next (Change, Outcome, Timeout => 30.0);
Add
function Add (Item : in out Watcher; Path : String) return Watch_Id
Register an existing file or directory. The final symbolic-link component is followed. Registration is persistent between Next calls, so a later Next observes a coalesced hint for changes made meanwhile. Add performs pathname metadata syscalls directly on the calling lane.
Parameters
- Item
Open serialized watcher
- Path
Existing file or directory to observe
Return value
Stable registration identifier
Raised exceptions
- Device_Error
Item is closed, capacity is exhausted, Path is empty or contains NUL, or registration fails
Change_Kind
type Change_Kind is (Contents_Changed, Metadata_Changed, Identity_Changed, Watch_Invalidated, Events_Lost);
Portable change categories. Each value is a coalesced hint rather than a claim that exactly one filesystem operation occurred.
Enumeration literals
- Contents_Changed
File data or directory entries may have changed
- Metadata_Changed
Attributes or link metadata may have changed
- Identity_Changed
The watched pathname may name a different object
- Watch_Invalidated
The registration must be removed and recreated
- Events_Lost
Kernel detail was lost; rebuild relevant cached state
Change_Set
type Change_Set is array (Change_Kind) of Boolean with Pack;
Set of coalesced hints reported for one watch.
Close
procedure Close (Item : in out Watcher)
Release all registrations and the platform queue. Repeated calls are harmless. The watcher is invalidated even if a close reports failure.
Parameters
- Item
Serialized watcher whose resources are released
Raised exceptions
- Device_Error
A platform close or removal reports failure
Default_Capacity
Default_Capacity : constant Positive := 64;
Number of paths accepted by a default-discriminated watcher. Callers that need another bound select it on the Watcher object.
File_Event
type File_Event is record
Watch : Watch_Id := No_Watch;
Changes : Change_Set := No_Changes;
end record;
One notification associated with a still-known registration.
Record fields
- Watch
Registration returned by Add
- Changes
Coalesced portable change hints
Finish
procedure Finish (Operation : in out Next_Operation; Result : out File_Event; Outcome : out Wait_Outcome)
Consume one terminal watcher operation and publish the familiar Next outputs. Timeout is a successful operation result with Timed_Out; provider failure remains retained until this call.
Parameters
- Operation
Terminal watcher operation
- Result
Event when Outcome is Ready, otherwise an empty event
- Outcome
Ready or Timed_Out
Raised exceptions
- Device_Error
Watcher state or event draining failed
- Operation_Cancelled
Operation was cancelled
Is_Open
function Is_Open (Item : Watcher) return Boolean
Report whether Item currently owns a platform queue.
Parameters
- Item
Watcher to inspect
Return value
True after Open and before Close
Next
function Next
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Watcher'Class;
Timeout : Duration := Infinite) return Next_Operation
Start one task-aware watcher wait without suspending the owner. This overload omits Interrupts because interruption composes as a separate readiness operation in the same completion set.
Parameters
- Set
Completion set that owns the operation slot
- Item
Open watcher with at least one registration; must outlive the returned operation
- Timeout
Relative deadline; negative waits indefinitely and zero immediately probes and drains already-queued native events
Return value
Started limited watcher operation
Next
procedure Next
(Item : in out Watcher;
Result : out File_Event;
Outcome : out Wait_Outcome;
Timeout : Duration := Infinite;
Interrupts : Interrupt_Set := No_Interrupts)
Return one pending coalesced event, wait until one becomes available, or report timeout/interruption. Negative Timeout waits indefinitely; zero performs an immediate drain. One monotonic deadline spans stale kernel records and readiness retries. Interrupt descriptors are observed but never consumed. A lightweight task suspends only itself; a native task blocks only its pthread. Result is empty unless Outcome is Ready.
Parameters
- Item
Open serialized watcher with at least one registration
- Result
Event returned when Outcome is Ready
- Outcome
Ready, Timed_Out, or Interrupted
- Timeout
Relative monotonic deadline in seconds
- Interrupts
Borrowed readable interruption descriptors
Raised exceptions
- Device_Error
State, readiness, or event draining fails
Next
procedure Next
(Item : not null access Watcher'Class; Timeout : Duration := Infinite; Operation : in out Next_Operation)
Start or restart a watcher wait in an established operation object.
Parameters
- Item
Open watcher with at least one registration
- Timeout
Relative deadline
- Operation
Fresh, released, or consumed watcher operation
Next_Operation
type Next_Operation is new Flyology.Operations.Operation with private;
Scoped wait for one coalesced file event. The watcher remains exclusively borrowed until Finish or finalization terminalizes the operation.
No_Changes
No_Changes : constant Change_Set := (others => False);
Empty hint set.
No_Watch
No_Watch : constant Watch_Id := 0;
Sentinel that never identifies a registration.
Open
procedure Open (Item : in out Watcher)
Allocate the platform queue. Repeated calls while open are harmless. The metadata syscall executes directly on the calling lane.
Parameters
- Item
Serialized watcher to initialize
Raised exceptions
- Device_Error
Queue creation or configuration fails
Operation_Cancelled
Operation_Cancelled : exception renames Flyology.Operations.Operation_Cancelled;
Raised by Finish after a scoped watcher wait is cancelled.
Remove
procedure Remove (Item : in out Watcher; Id : Watch_Id)
Remove Id and release its platform resources. Queued hints for Id are discarded. The logical identifier is retired even when the platform removal reports failure, so callers must not retry the same Id. Removing No_Watch or an unknown identifier is rejected.
Parameters
- Item
Open serialized watcher
- Id
Registration to remove
Raised exceptions
- Device_Error
Item is closed, Id is unknown, or removal fails
Watch_Id
type Watch_Id is new Interfaces.Unsigned_64;
Stable identifier for one registration during its owner's lifetime.
Watcher
type Watcher (Capacity : Positive := Default_Capacity) is
new Ada.Finalization.Limited_Controlled with private;
Controlled owner of one platform queue and up to Capacity watched paths. Operations are intentionally unsynchronized: one task must serialize Open, Add, Remove, Next, and Close. Finalization is nonraising.