QLockFile Class

メンバ関数のドキュメント

[explicit] QLockFile::QLockFile(const QString &fileName)

新しいロックファイルオブジェクトを作成します。このオブジェクトはロックされていない状態で作成されます。lock() またはtryLock() を呼び出す際、fileName という名前のロックファイルがまだ存在しない場合は、そのファイルが作成されます。

lock() およびunlock()も参照してください 。

[noexcept] QLockFile::~QLockFile()

ロックファイルオブジェクトを破棄します。ロックが取得されていた場合、この操作によりロックファイルが削除され、ロックが解放されます。

QLockFile::LockError QLockFile::error() const

ロックファイルのエラーステータスを返します。

tryLock() が `false` を返した場合、この関数を呼び出すことで、ロックに失敗した原因を特定できます。

QString QLockFile::fileName() const

ロックファイルのファイル名を返します

bool QLockFile::getLockInfo(qint64 *pid, QString *hostname, QString *appname) const

ロックファイルの現在の所有者に関する情報を取得します。

tryLock() が `false` を返し、error() が `LockFailedError` を返す場合、この関数を呼び出すことで、既存のロックファイルに関する詳細情報を取得できます。

• アプリケーションのPID（pid で返される）
• 実行されているhostname （ネットワークファイルシステムの場合に有用）
• そのロックファイルを作成したアプリケーションの名前（appname で返されます）、

なお、tryLock() は、この PID を持つ実行中のアプリケーションが存在しない場合、ファイルを自動的に削除するため、LockFailedError が呼び出されるのは、この PID を持つアプリケーションが存在する場合に限られます（ただし、そのアプリケーションとは無関係である可能性もあります）。

これを利用して、ユーザーにロックファイルの存在を通知し、削除するかどうかを選択させることができます。removeStaleLockFile() を使用してファイルを削除した後、アプリケーションは再度tryLock() を呼び出すことができます。

この関数は、情報を正常に取得できた場合はtrue を返し、ロックファイルが存在しないか、期待されるデータが含まれていない場合はfalseを返します。これは、tryLock()が失敗してからこの関数が呼び出されるまでの間にロックファイルが削除された場合に発生する可能性があります。その場合は、単にtryLock()を再度呼び出してください。

bool QLockFile::isLocked() const

このQLockFile インスタンスによってロックが取得されていた場合はtrue を返し、そうでない場合はfalse を返します。

lock()、unlock()、およびtryLock()も参照してください 。

bool QLockFile::lock()

ロックファイルを作成します。

別のプロセス（またはスレッド）がすでにロックファイルを作成している場合、この関数は、そのプロセス（またはスレッド）がロックを解放するまでブロックされます。

最初にロックを解除せずに、同じスレッドから同じロックに対してこの関数を複数回呼び出すことは許可されません。ファイルが再帰的にロックされている場合、この関数はデッドロックを起こします。

ロックが取得できた場合は `true ` を返し、親ディレクトリへのアクセス権がないなど、回復不可能なエラーによりロックを取得できなかった場合は `false` を返します。

unlock() およびtryLock()も参照してください 。

bool QLockFile::removeStaleLockFile()

既存のロックファイルを強制的に削除しようとしています。

短期間の操作を保護する場合、この関数を呼び出すことは推奨されません。QLockFile は、ロックファイルがstaleLockTime()よりも古い場合、自動的に削除を行うためです。

このメソッドは、リソースを長期間保護する場合、つまりstaleLockTime(0) を使用する場合にのみ呼び出すべきであり、かつtryLock() がLockFailedError を返した後、ユーザーがロックファイルの削除に同意した場合に限ります。

成功した場合はtrue を返し、ロックファイルを削除できなかった場合はfalseを返します。これは、Windowsにおいて、ロックを保持しているアプリケーションがまだ実行中の場合に発生します。

void QLockFile::setStaleLockTime(int staleLockTime)

staleLockTime を、ロックファイルが古くなったとみなされるまでの時間をミリ秒単位で設定します。デフォルト値は 30000、つまり 30 秒です。 アプリケーションで通常、ファイルを 30 秒以上ロックし続ける場合（たとえば、数メガバイトのデータを 2 分間保存する場合など）、setStaleLockTime() を使用してより大きな値を設定する必要があります。

staleLockTime の値は、lock() およびtryLock() によって、既存のロックファイルがいつ「古くなった」、つまりクラッシュしたプロセスによって残されたものとみなされるかを判断するために使用されます。これは、その間に PID が再利用されてしまった場合に有用であり、ロックファイルが長時間存在し続けているという事実によって、そのファイルが古くなったものであることを検出する方法の一つとなります。

これはオーバーロードされた関数であり、以下の呼び出しと同等です：

setStaleLockTime(std::chrono::milliseconds{staleLockTime});

staleLockTime()も参照してください 。

[since 6.2] void QLockFile::setStaleLockTime(std::chrono::milliseconds staleLockTime)

ロックファイルが古くなったとみなされるまでの間隔をstaleLockTime に設定します。デフォルト値は30秒です。

アプリケーションで通常、ファイルを30秒以上ロックし続ける場合（たとえば、数メガバイトのデータを2分間保存する場合など）、setStaleLockTime() を使用してより大きな値を設定する必要があります。

staleLockTime() の値は、lock() およびtryLock() によって、既存のロックファイルがいつ「古くなった」、つまりクラッシュしたプロセスによって残されたものとみなされるかを判断するために使用されます。これは、その間に PID が再利用された場合に有用であり、ロックファイルが長時間存在しているという事実に基づいて、古くなったロックファイルを検出する方法の一つとなります。

この値を 0 または負の値に設定すると、ロックファイルのタイムスタンプの検証が無効になります。QLockFile は、その内容からロックを行っているプロセスがもはや実行されていないことが判明した場合、引き続き古いロックファイルを検出します。

この関数は Qt 6.2 で導入されました。

staleLockTime()も参照してください 。

int QLockFile::staleLockTime() const

ロックファイルが古くなったとみなされるまでの時間をミリ秒単位で返します。

setStaleLockTime()も参照してください 。

[since 6.2] std::chrono::milliseconds QLockFile::staleLockTimeAsDuration() const

ロックファイルが古くなったとみなされるまでの時間を表す std::chrono::milliseconds オブジェクトを返します。

この関数は Qt 6.2 で導入されました。

setStaleLockTime()も参照してください 。

bool QLockFile::tryLock(int timeout)

ロックファイルの作成を試みます。この関数は、ロックを取得できた場合にtrue を返し、そうでない場合はfalse を返します。別のプロセス（または別のスレッド）がすでにロックファイルを作成している場合、この関数はロックファイルが利用可能になるまで、最大timeout ミリ秒待機します。

注：timeout として負の数を渡すことは、lock() を呼び出すことと同じです。つまり、timeout が負の場合、この関数はロックファイルがロック可能になるまで無限に待機します。

ロックが取得された場合、別のプロセス（またはスレッド）が正常にロックを行うには、unlock() を使用してロックを解除する必要があります。

同じスレッドから、最初にロックを解除せずに同じロックに対してこの関数を複数回呼び出すことは許可されていません。ファイルを再帰的にロックしようとすると、この関数は常にfalse を返します。

lock() およびunlock()も参照してください 。

[since 6.2] bool QLockFile::tryLock(std::chrono::milliseconds timeout = std::chrono::milliseconds::zero())

ロックファイルの作成を試みます。この関数は、ロックを取得できた場合はtrue を返し、そうでない場合はfalse を返します。別のプロセス（またはスレッド）がすでにロックファイルを作成している場合、この関数はロックファイルが利用可能になるまで、最大timeout の間待機します。

ロックが取得された場合、別のプロセス（またはスレッド）が正常にロックを行うには、unlock() を使用してロックを解除する必要があります。

同じスレッドから、最初にロックを解除せずに同じロックに対してこの関数を複数回呼び出すことは許可されていません。ファイルを再帰的にロックしようとすると、この関数は常にfalse を返します。

この関数は Qt 6.2 で導入されました。

lock() およびunlock()も参照してください 。

void QLockFile::unlock()

ロックファイルを削除して、ロックを解除します。

事前にファイルをロックせずに unlock() を呼び出しても、何もしません。

lock() およびtryLock()も参照してください 。