Description
Maintains a bounded set of directory registrations below one root. Events describe the complete tree rather than one internal registration.
Close
procedure Close (Item : in out Recursive_Watcher)
Release every directory registration and owned pathname. Repeated calls are harmless. Item becomes closed even when cleanup reports failure.
Parameters
- Item
Serialized recursive watcher to close
Raised exceptions
- Device_Error
Platform cleanup reports failure
Coverage_Is_Complete
function Coverage_Is_Complete (Item : Recursive_Watcher) return Boolean
Report whether the last scan covered every real directory below Root and registered each one.
Parameters
- Item
Recursive watcher to inspect
Return value
True only while Item is open with complete coverage
Directory_Count
function Directory_Count (Item : Recursive_Watcher) return Natural
Return the number of retained logical directory registrations. While coverage is incomplete, this count can include an obsolete pathname and omit a current directory.
Parameters
- Item
Recursive watcher to inspect
Return value
Retained logical directory registration count
Finish
procedure Finish
(Operation : in out Next_Operation; Result : out Recursive_Event; Outcome : out Wait_Outcome)
Consume a terminal recursive operation. A readiness timeout is a successful operation with Timed_Out. Reconciliation failure remains retained until this call.
Parameters
- Operation
Terminal recursive watcher operation
- Result
Reconciled tree event when Outcome is Ready
- Outcome
Ready or Timed_Out
Raised exceptions
- Device_Error
Watcher state, child wait, or reconciliation failed
- Operation_Cancelled
Operation was cancelled
Is_Open
function Is_Open (Item : Recursive_Watcher) return Boolean
Report whether Item currently owns a recursive watch.
Parameters
- Item
Recursive watcher to inspect
Return value
True after Open and before Close or root invalidation
Next
function Next
(Set : not null access Flyology.Operations.Completion_Set'Class;
Item : not null access Recursive_Watcher'Class;
Timeout : Duration := Infinite) return Next_Operation
Start one recursive watcher wait without suspending the owner. The operation composes the ordinary File_Watches.Next overload internally; its set therefore needs two slots, plus any gate that observes it.
Parameters
- Set
Completion set that owns parent and hidden child slots
- Item
Open recursive watcher that outlives the operation
- Timeout
Relative readiness deadline
Return value
Started limited recursive watcher operation
Next
procedure Next
(Item : in out Recursive_Watcher;
Result : out Recursive_Event;
Outcome : out Wait_Outcome;
Timeout : Duration := Infinite;
Interrupts : Interrupt_Set := No_Interrupts)
Wait for one tree hint, reconcile the directory registrations, and return a tree-wide event. Timeout and Interrupts apply to the readiness wait. Reconciliation starts after readiness and is not bounded by that deadline. Interrupt descriptors are observed but never consumed. A lightweight task suspends for readiness but performs reconciliation on its event-loop pthread.
Parameters
- Item
Open serialized recursive watcher
- Result
Tree-wide event returned when Outcome is Ready
- Outcome
Ready, Timed_Out, or Interrupted
- Timeout
Relative monotonic readiness deadline in seconds
- Interrupts
Borrowed readable interruption descriptors
Raised exceptions
- Device_Error
State, readiness, discovery, registration, or cleanup fails
Next
procedure Next
(Item : not null access Recursive_Watcher'Class;
Timeout : Duration := Infinite;
Operation : in out Next_Operation)
Start or restart a recursive watcher wait in an established object.
Parameters
- Item
Open recursive watcher that outlives the operation
- Timeout
Relative readiness deadline
- Operation
Fresh, released, or consumed recursive operation
Next_Operation
type Next_Operation (Owner : not null access Flyology.Operations.Completion_Set'Class) is
new Flyology.Operations.Operation (Owner)
with record
State : Next_Operation_State (Owner);
end record;
Scoped recursive wait. Its terminal result includes both the raw readiness hint and the completed registration reconciliation. The visible opaque State component is solely the build-in-place storage required by Ada for a child operation constrained by the same set.
Record fields
- Owner
Completion set that owns parent and child slots
- State
Opaque build-in-place child storage
Next_Operation_State
type Next_Operation_State (Owner : not null access Flyology.Operations.Completion_Set'Class) is
limited private;
Opaque storage for the recursively composed child operation. @exclude
Record fields
- Owner
Completion set shared with the child operation
Open
procedure Open (Item : in out Recursive_Watcher; Root : String)
Discover Root and register every real directory below it. The final symbolic-link component of Root is followed. Symbolic links found below Root are not traversed. Repeated calls for the same open root are harmless. Initial discovery is transactional and requires complete coverage.
Parameters
- Item
Closed serialized recursive watcher
- Root
Existing directory tree to observe
Raised exceptions
- Device_Error
Root is invalid or not a directory, discovery or registration fails, capacity is insufficient, or Item is already open for another root
Recursive_Event
type Recursive_Event is record
Changes : Change_Set := No_Changes;
Registrations_Changed : Boolean := False;
Directory_Count : Natural := 0;
Coverage_Complete : Boolean := False;
end record;
Tree-wide notification returned after registration reconciliation.
Record fields
- Changes
Coalesced hints that apply to the watched tree
- Registrations_Changed
Whether reconciliation added or removed a directory registration
- Directory_Count
Current number of retained logical directory registrations
- Coverage_Complete
Whether the last scan covered every real directory below the root and registered each one
Recursive_Watcher
type Recursive_Watcher (Capacity : Positive := Default_Capacity) is
new Ada.Finalization.Limited_Controlled with private;
Controlled owner of one recursive directory watch. Capacity bounds the root plus all real subdirectories. The default is 64. Operations are intentionally unsynchronized and can perform directory metadata work.
Refresh
procedure Refresh (Item : in out Recursive_Watcher; Result : out Recursive_Event)
Reconcile the current directory tree with its registrations. Capacity overflow or incomplete discovery preserves the previous registration set, reports incomplete coverage, and sets Events_Lost. If Root no longer exists, Refresh closes Item and reports Identity_Changed and Watch_Invalidated. Directory discovery and registration syscalls execute on the calling lane.
Parameters
- Item
Open serialized recursive watcher
- Result
Reconciliation outcome
Raised exceptions
- Device_Error
Item is closed or discovery, registration, or cleanup fails