poll_fd(fd, timeout_s::Real=-1; readable=false, writable=false)

Monitor a file descriptorfd for changes in the read or write availability, and with a timeout given bytimeout_s seconds.

The keyword arguments determine which of read and/or write status should be monitored; at least one of them must be set totrue.

The returned value is an object with boolean fieldsreadable,writable, andtimedout, giving the result of the polling.

poll_file(path::AbstractString, interval_s::Real=5.007, timeout_s::Real=-1) -> (previous::StatStruct, current)

Monitor a file for changes by polling everyinterval_s seconds until a change occurs ortimeout_s seconds have elapsed. Theinterval_s should be a long period; the default is 5.007 seconds.

Returns a pair of status objects(previous, current) when a change is detected. Theprevious status is always aStatStruct, but it may have all of the fields zeroed (indicating the file didn't previously exist, or wasn't previously accessible).

Thecurrent status object may be aStatStruct, anEOFError (indicating the timeout elapsed), or some otherException subtype (if thestat operation failed - for example, if the path does not exist).

To determine when a file was modified, comparecurrent isa StatStruct && mtime(prev) != mtime(current) to detect notification of changes. However, usingwatch_file for this operation is preferred, since it is more reliable and efficient, although in some situations it may not be available.

watch_file(path::AbstractString, timeout_s::Real=-1)

Watch file or directorypath for changes until a change occurs ortimeout_s seconds have elapsed. This function does not poll the file system and instead uses platform-specific functionality to receive notifications from the operating system (e.g. via inotify on Linux). See the NodeJS documentation linked below for details.

The returned value is an object with boolean fieldsrenamed,changed, andtimedout, giving the result of watching the file.

This behavior of this function varies slightly across platforms. Seehttps://nodejs.org/api/fs.html#fs_caveats for more detailed information.

watch_folder(path::AbstractString, timeout_s::Real=-1)

Watches a file or directorypath for changes until a change has occurred ortimeout_s seconds have elapsed. This function does not poll the file system and instead uses platform-specific functionality to receive notifications from the operating system (e.g. via inotify on Linux). See the NodeJS documentation linked below for details.

This will continuing tracking changes forpath in the background untilunwatch_folder is called on the samepath.

The returned value is an pair where the first field is the name of the changed file (if available) and the second field is an object with boolean fieldsrenamed,changed, andtimedout, giving the event.

This behavior of this function varies slightly across platforms. Seehttps://nodejs.org/api/fs.html#fs_caveats for more detailed information.

unwatch_folder(path::AbstractString)

Stop background tracking of changes forpath. It is not recommended to do this while another task is waiting forwatch_folder to return on the same path, as the result may be unpredictable.

mkpidlock([f::Function], at::String, [pid::Cint]; kwopts...)mkpidlock(at::String, proc::Process; kwopts...)

Create a pidfile lock for the path "at" for the current process or the process identified by pid or proc. Can take a function to execute once locked, for usage indo blocks, after which the lock will be automatically closed. If the lock fails andwait is false, then an error is thrown.

The lock will be released by eitherclose, afinalizer, or shortly afterproc exits. Make sure the return value is live through the end of the critical section of your program, so thefinalizer does not reclaim it early.

Optional keyword arguments:

• mode: file access mode (modified by the process umask). Defaults to world-readable.
• poll_interval: Specify the maximum time to between attempts (ifwatch_file doesn't work)
• stale_age: Delete an existing pidfile (ignoring the lock) if it is older than this many seconds, based on its mtime. The file won't be deleted until 5x longer than this if the pid in the file appears that it may be valid. Or 25x longer ifrefresh is overridden to 0 to disable lock refreshing. By default this is disabled (stale_age = 0), but a typical recommended value would be about 3-5x an estimated normal completion time.
• refresh: Keeps a lock from becoming stale by updating the mtime every interval of time that passes. By default, this is set tostale_age/2, which is the recommended value.
• wait: If true, block until we get the lock, if false, raise error if lock fails.

trymkpidlock([f::Function], at::String, [pid::Cint]; kwopts...)trymkpidlock(at::String, proc::Process; kwopts...)

Likemkpidlock except returnsfalse instead of waiting if the file is already locked.

close(lock::LockMonitor)

Release a pidfile lock.

open_exclusive(path::String; mode, poll_interval, wait, stale_age, refresh) :: File

Create a new a file for read-write advisory-exclusive access. Ifwait isfalse then error out if the lock files exist otherwise block until we get the lock.

For a description of the keyword arguments, seemkpidlock.

tryopen_exclusive(path::String, mode::Integer = 0o444) :: Union{Void, File}

Try to create a new file for read-write advisory-exclusive access, return nothing if it already exists.

write_pidfile(io, pid)

Write our pidfile format to an open IO descriptor.

parse_pidfile(file::Union{IO, String}) => (pid, hostname, age)

Attempt to parse our pidfile format, replaced an element with (0, "", 0.0), respectively, for any read that failed.

stale_pidfile(path::String, stale_age::Real, refresh::Real) :: Bool

Helper function foropen_exclusive for deciding if a pidfile is stale.

isvalidpid(hostname::String, pid::Cuint) :: Bool

Attempt to conservatively estimate whether pid is a valid process id.

Base.touch(::Pidfile.LockMonitor)

Update themtime on the lock, to indicate it is still fresh.

See also therefresh keyword in themkpidlock constructor.