File Events
FileWatching.poll_fd — Function
poll_fd(fd, timeout_s::Real=-1; readable=false, writable=false)ファイルディスクリプター fd について、読み取りまたは書き込みが可能になったかを、timeout_s 秒のタイムアウトで監視します。
キーワード引数で、読み取り状態と書き込み状態のどちらを監視するか(または両方を監視するか)を指定します。少なくとも一方を true に設定する必要があります。
戻り値は、ポーリング結果を示すブール値フィールド readable、writable、timedout を持つオブジェクトです。
これは、FDWatcher 上で wait を呼び出す薄いラッパーです。後者が機能を実装していますが、使用後にユーザーが手動で close を呼び出す必要があり、呼び出さないと深刻なクラッシュを招くおそれがあります。
FileWatching.poll_file — Function
poll_file(path::AbstractString, interval_s::Real=5.007, timeout_s::Real=-1) -> (previous::StatStruct, current)ファイルに変更があったかどうかを、interval_s 秒ごとにポーリングして監視します。変更が検出されるか、timeout_s 秒が経過すると監視を終了します。interval_s は長めの時間に設定してください。デフォルトは 5.007 秒です。
変更が検出されると、ステータスオブジェクトのペア (previous, current) を返します。previous のステータスは常に StatStruct ですが、すべてのフィールドがゼロになっている場合があります(ファイルが以前は存在しなかった、またはアクセスできなかったことを示します)。
current のステータスオブジェクトは、StatStruct、EOFError(タイムアウトが経過したことを示します)、またはその他の Exception サブタイプ(stat 操作が失敗した場合。たとえば、パスが存在しない場合)になることがあります。
ファイルがいつ変更されたかを判定するには、!(current isa StatStruct && prev == current) を比較して、mtime または inode の変更通知を検出します。ただし、この操作には watch_file を使うことを推奨します。こちらのほうが信頼性と効率に優れていますが、状況によっては利用できない場合があります。
これは、機能を実装する PollingFileWatcher 上で wait を呼び出す薄いラッパーです。ただし、この関数では poll_file の連続した呼び出しの間に小さな競合ウィンドウがあり、その間にファイルが変更されても検出されない可能性があります。
FileWatching.watch_file — Function
watch_file(path::AbstractString, timeout_s::Real=-1)ファイルまたはディレクトリpathを監視し、変更が発生するか、timeout_s秒が経過するまで待機します。この関数はファイルシステムをポーリングするのではなく、OSから通知を受け取るためのプラットフォーム固有の機能(Linuxのinotifyなど)を使用します。詳しくは、以下にリンクされているNodeJSのドキュメントを参照してください。
戻り値は、ファイルの監視結果を示すブール値フィールドrenamed、changed、timedoutを持つオブジェクトです。
これは、FileMonitor上でwaitを呼び出す薄いラッパーです。連続するwatch_fileの呼び出しの間には短い競合状態があり、その間にファイルが変更されても検出されない可能性があります。この競合を避けるには、次を直接使用してください。
fm = FileMonitor(path)
wait(fm)その際、waitするたびに同じfmを再利用してください。
FileWatching.watch_folder — Function
watch_folder(path::AbstractString, timeout_s::Real=-1)ファイルまたはディレクトリ path を監視し、変更が発生するか、timeout_s 秒が経過するまで待機します。この関数はファイルシステムをポーリングするのではなく、OSから通知を受け取るためのプラットフォーム固有の機能(Linuxのinotifyなど)を使用します。詳しくは、以下にリンクされているNodeJSのドキュメントを参照してください。
同じ path に対して unwatch_folder が呼び出されるまで、バックグラウンドで path の変更の追跡が続きます。
戻り値はペアで、第1フィールドは変更されたファイルの名前(取得できる場合)、第2フィールドはイベントを示すブール値フィールド renamed、changed、timedout を持つオブジェクトです。
この関数は、タイムアウト機能を追加したうえで、FolderMonitor 上で wait を呼び出す薄いラッパーです。
FileWatching.unwatch_folder — Function
unwatch_folder(path::AbstractString)path の変更に対するバックグラウンド追跡を停止します。同じパスで別のタスクが watch_folder の返却を待っている間は、予期しない結果になる可能性があるため、この操作は推奨されません。
FileWatching.FileMonitor — Type
FileMonitor(path::AbstractString)変更が発生するまで、ファイルまたはディレクトリ path(存在している必要があります)を監視します。この関数はファイルシステムをポーリングするのではなく、OSから通知を受け取るためにプラットフォーム固有の機能(Linuxのinotifyなど)を使用します。詳しくは、以下にリンクされているNodeJSのドキュメントを参照してください。
fm = FileMonitor(path)は自動リセット型のイベントのように動作します。そのため、wait(fm)は、指定されたパスに最初に存在したファイルで少なくとも1つのイベントが発生するまでブロックし、その後、最後に呼び出したwaitが返されてから発生したすべての変更を要約する、ブール値フィールド renamed、changed、timedoutを持つオブジェクトを返します。
FileWatching.FolderMonitor — Type
FolderMonitor(folder::AbstractString)ファイルまたはディレクトリ path を監視し、変更が発生するまで待機します。この関数はファイルシステムをポーリングするのではなく、OSから通知を受け取るためのプラットフォーム固有の機能(Linuxのinotifyなど)を使用します。詳しくは、以下にリンクされているNodeJSのドキュメントを参照してください。
この関数はChannelと同様に動作するため、take!(またはwait)を呼び出すと、何らかの変更が発生するまで処理がブロックされます。wait 関数はペアを返します。1つ目のフィールドは変更されたファイルの名前(取得できる場合)、2つ目のフィールドは、そのファイルで発生したイベントを示すブール値フィールド renamed と changed を持つオブジェクトです。
FileWatching.PollingFileWatcher — Type
PollingFileWatcher(path::AbstractString, interval_s::Real=5.007)ファイルに変更が発生するか、timeout_s 秒が経過するまで、stat を interval_s 秒ごとにポーリングして、ファイルの変更を監視します。interval_s には長い時間を指定してください。デフォルトは 5.007 秒です。最新ではないものの直近の結果を取得するには、対象に対して stat を呼び出します。
これは自動リセット型イベントのように動作します。そのため、wait を呼び出すと、wait の呼び出し開始時に取得した前回の値から、stat の結果が変わるまでブロックされます。wait 関数は、前回 wait を呼び出してから stat の変更が検出されると、ステータスオブジェクトのペア (previous, current) を返します。previous のステータスは常に StatStruct ですが、すべてのフィールドがゼロになっている場合があります(ファイルが以前は存在しなかった、またはアクセスできなかったことを示します)。
current のステータスオブジェクトは、StatStruct、EOFError(このオブジェクトを閉じて待機をキャンセルした場合)、またはその他の Exception サブタイプ(stat 操作が失敗した場合。たとえば、パスが削除された場合)になることがあります。ファイルがその後複数回変更されていると、stat の値が古くなっている可能性があることに注意してください。
この操作には FileMonitor を使用することを推奨します。より信頼性が高く効率的ですが、状況によっては利用できない場合があります。
FileWatching.FDWatcher — Type
FDWatcher(fd::Union{RawFD,WindowsRawSocket}, readable::Bool, writable::Bool)ファイル記述子 fd を監視し、読み取りまたは書き込みが可能になったことを検知します。
キーワード引数で、読み取り状態と書き込み状態のどちらを監視するか(または両方を監視するか)を指定します。少なくとも一方には true を設定する必要があります。
戻り値は、ポーリング結果を示すブール値フィールド readable、writable、timedout を持つオブジェクトです。
これはレベル検知型のイベントとして動作します。そのため、wait を呼び出すと、いずれかの条件が満たされるまでブロックします。ただし、条件が解消される(読み取るデータがなくなる、書き込みバッファに空きがなくなる、またはその両方)までは、その後もブロックせずに戻り続けます。
Pidfile
アドバイザリ pidfile(ロックファイル)を作成するためのシンプルなユーティリティツールです。
Primary Functions
FileWatching.Pidfile.mkpidlock — Function
mkpidlock([f::Function], at::String, [pid::Cint]; kwopts...)
mkpidlock(at::String, proc::Process; kwopts...)現在のプロセス、または pid もしくは proc で指定したプロセスのために、パス "at" に pidfile ロックを作成します。ロック取得後に実行する関数を指定できます。これはdoブロックで使用でき、実行後にロックは自動的に閉じられます。ロックに失敗し、waitがfalseの場合は、エラーがスローされます。
ロックは、close、finalizer、またはprocの終了後まもなく解放されます。プログラムのクリティカルセクションが終わるまで戻り値が有効な状態を保つようにしてください。そうしないと、finalizerによって早期に回収される可能性があります。
省略可能なキーワード引数:
mode: ファイルのアクセスモード(プロセスの umask によって変更されます)。デフォルトでは、すべてのユーザーが読み取り可能です。poll_interval: 試行間の最大待ち時間を指定します(watch_fileが機能しない場合)。stale_age: mtime に基づき、指定した秒数より古い既存の pidfile を(ロックを無視して)削除します。ファイル内の pid が有効である可能性がある場合、指定時間の5倍が経過するまでファイルは削除されません。ロックの更新を無効にするためにrefreshを0に上書きした場合は、25倍の時間が経過するまで削除されません。デフォルトでは無効です(stale_age= 0)。通常の完了時間の推定値の約3~5倍を設定するのが一般的な推奨値です。refresh: 一定時間ごとに mtime を更新し、ロックが古くならないようにします。デフォルトではstale_age/2に設定されており、これが推奨値です。wait: true の場合はロックを取得するまで待機し、false の場合はロックに失敗するとエラーをスローします。
FileWatching.Pidfile.trymkpidlock — Function
trymkpidlock([f::Function], at::String, [pid::Cint]; kwopts...)
trymkpidlock(at::String, proc::Process; kwopts...)mkpidlockと同様ですが、ファイルがすでにロックされている場合は待機せずにfalseを返します。
Base.close — Method
close(lock::LockMonitor)pidfile のロックを解放します。
Helper Functions
FileWatching.Pidfile.open_exclusive — Function
open_exclusive(path::String; mode, poll_interval, wait, stale_age, refresh) :: File読み書き可能なアドバイザリ排他アクセス用の新しいファイルを作成します。wait が false の場合、ロックファイルが存在すればエラーを返し、存在しなければロックを取得できるまで待機します。
キーワード引数の説明については、mkpidlock を参照してください。
FileWatching.Pidfile.tryopen_exclusive — Function
tryopen_exclusive(path::String, mode::Integer = 0o444) :: Union{Void, File}読み書き可能なアドバイザリ排他アクセス用に新しいファイルの作成を試み、すでに存在する場合は nothing を返します。
FileWatching.Pidfile.write_pidfile — Function
write_pidfile(io, pid)pidfile形式を開いているIOディスクリプターに書き込みます。
FileWatching.Pidfile.parse_pidfile — Function
parse_pidfile(file::Union{IO, String}) => (pid, hostname, age)pidfile形式の解析を試み、読み取りに失敗した場合は、それぞれの要素を(0, "", 0.0)に置き換えました。
FileWatching.Pidfile.stale_pidfile — Function
stale_pidfile(path::String, stale_age::Real, refresh::Real) :: Boolpidfile が古いかどうかを判定する open_exclusive 用のヘルパー関数。
FileWatching.Pidfile.isvalidpid — Function
isvalidpid(hostname::String, pid::Cuint) :: Boolpidが有効なプロセスIDかどうかを保守的に推定します。
Base.Filesystem.touch — Method
Base.touch(::Pidfile.LockMonitor)ロックのmtimeを更新して、まだ新しいことを示します。
mkpidlockコンストラクターのrefreshキーワードも参照してください。