39 lines
2.5 KiB
Markdown
39 lines
2.5 KiB
Markdown
# Live reconfiguration
|
|
|
|
`AutoUpdate` starts polling the loaded file. `Watch` starts it if necessary and
|
|
subscribes to notifications. Option variants configure the polling interval
|
|
(minimum 100ms), debounce, subscriber limit, reload timeout and permission checks.
|
|
Options for an already-running watcher stay unchanged; stop/restart to change them.
|
|
|
|
One worker reads and fingerprints the regular file per poll, including same-size,
|
|
same-timestamp edits and atomic replacements. Both successful and erroneous reads
|
|
must settle for the debounce interval. Stable errors are reported once per observed
|
|
state. Deletion preserves the last valid state, and recreation can reload normally.
|
|
This trades one file read per poll for reliable detection of metadata-preserving edits.
|
|
|
|
Before publishing, the worker checks its context, current watcher identity, watched
|
|
path and source generation under the Config lock. Type checks and allocation finish
|
|
before the final timeout check. Expired, stopped or superseded operations cannot
|
|
publish. ReloadTimeout limits publication eligibility; it cannot forcibly interrupt
|
|
a kernel filesystem operation. Reads never hold the Config lock.
|
|
Timed-out operations retry on later polls even if the content is unchanged; repeated
|
|
timeouts for the same observation emit only one notification until recovery.
|
|
|
|
Events are changed registered paths, or `file_deleted`, `permissions_changed`,
|
|
`reload_timeout`, `reload_error:<detail>`, and `precedence:<path>`. A path event means
|
|
the effective value changed; a file value masked by CLI need not notify. With
|
|
VerifyPermissions (on by default), a change of the group/world permission bits is
|
|
reported once as `permissions_changed` and that version is not applied; the next
|
|
change applies under the new mode. While a watcher runs, a further Watch or
|
|
WatchWithOptions call subscribes to it and its options are ignored.
|
|
|
|
Notifications are buffered (10 entries) and best effort; a slow subscriber may miss
|
|
events and should read the latest full state. MaxWatchers bounds retained channels.
|
|
StopAutoUpdate cancels publication and closes channels synchronously without waiting
|
|
under the Config lock. There is no goroutine per subscriber or per timed-out reload.
|
|
A new Watch call after stopping creates a new channel and worker.
|
|
|
|
`WatchFile` loads a replacement path before replacing the watcher and preserves its
|
|
options. Failure leaves the prior watcher and values active. Loading a different
|
|
file directly stops the previous watcher; call Watch to watch the new path.
|