ネイティブIPCキー

QSharedMemory クラスおよびQSystemSemaphore クラスは、「キー」と呼ばれるシステム全体の識別子を使用してリソースを識別します。低レベルのキー値およびキーの型は、QNativeIpcKey クラスを使用して Qt 内でカプセル化されています。このクラスは、QNativeIpcKey::toString() およびQNativeIpcKey::fromString() を通じて、他のプロセスとキーを交換するための適切な手段も提供します。

Qtは現在、これら2つのクラスに対して3つの異なるバックエンドをサポートしており、これらはQNativeIpcKey::Type 列挙型で利用可能な値に対応しています。

• POSIX リアルタイム拡張 (IEEE 1003.1b、POSIX.1b)
• X/Open システムインターフェース (XSI) または System V (SVr4)。現在は POSIX の一部となっていますが
• Windows プリミティブ

その名前が示す通り、WindowsプリミティブはWindowsオペレーティングシステムでのみ利用可能であり、そこではデフォルトのバックエンドとなります。他の2つは通常、Unixオペレーティングシステムの両方で利用可能です。以下の表は、Qt 6.6以降の一般的な利用状況の概要を示しています:

特定のキー型がサポートされているかどうかを判断するには、アプリケーションは QSharedMemory::isKeyTypeSupported() および QSystemSemaphore::isKeyTypeSupported() を呼び出す必要があります。

QNativeIpcKey また、導入以前の Qt アプリケーションとの互換性もサポートしています。以下のセクションでは、バックエンドの制限事項、文字列キー自体の内容、および互換性について詳しく説明します。

クロスプラットフォームで安全なキー形式

QNativeIpcKey::setNativeKey() およびQNativeIpcKey::nativeKey() は、低レベルのネイティブキーを扱います。このキーは、ネイティブ API で使用したり、Qt 以外のプロセスと共有したりすることができます（API については以下を参照してください）。 この形式は通常、クロスプラットフォーム対応ではないため、QSharedMemory とQSystemSemaphore の両方が、クロスプラットフォーム識別子文字列をネイティブキーに変換する関数（QSharedMemory::platformSafeKey() および QSystemSemaphore::platformSafeKey()）を提供しています。

ほとんどのプラットフォームでは、クロスプラットフォームキーの長さはファイル名と同じですが、Appleプラットフォームでは使用可能なバイト数が30バイトに厳しく制限されています（US-ASCII範囲外の文字を使用する場合は、UTF-8エンコーディングに注意してください）。 また、キーの形式もファイルパスの構成要素と同様であるため、Apple オペレーティングシステム上のサンドボックス化されたアプリケーションを除き、ファイル名で使用が許可されていない文字、特にパス構成要素を区切る文字（スラッシュおよびバックスラッシュ）を含んではなりません。 以下は、クロスプラットフォームで利用できるキーの適切な例です：「myapp」、「org.example.myapp」、「org.example.myapp-12345」。 キーが長くなりすぎないようにし、キーが各プラットフォームで許可されている文字のみを含むようにするのは、呼び出し側の責任であることに注意してください。Qt は、長すぎるキーを黙って切り捨てます。

Appleのサンドボックスに関する制限：アプリケーションがAppleオペレーティングシステムのサンドボックス内で実行されている場合、キーは<application group identifier>/<custom identifier> という非常に特定の形式でなければなりません。Apple App Storeを通じて配布されるすべてのアプリケーションには、暗黙的にサンドボックス化が適用されます。アプリケーションのグループ識別子の取得方法など、詳細については、こちらのAppleのドキュメントおよびこちらのドキュメントを参照してください。

ネイティブキーの形式

このセクションでは、サポートされているバックエンドのネイティブキーの形式について詳しく説明します。

POSIX リアルタイム

ネイティブキーはファイル名に似ており、スラッシュを除き、ファイル名で使用可能な任意の文字を含めることができます。POSIXでは、キー名の最初の文字がスラッシュであることが求められますが、それ以降のスラッシュの使用可否については規定されていません。 ほとんどのオペレーティングシステムでは、キーの長さはファイル名と同じですが、Appleのオペレーティングシステムでは32文字に制限されています（これには先頭のスラッシュと末尾のヌル文字が含まれるため、実際に使用可能な文字数は30文字のみとなります）。

以下は、ネイティブ POSIX キーの良い例です: "/myapp", "/org.example.myapp", "/org.example.myapp-12345"。

QSharedMemory::platformSafeKey() および QSystemSemaphore::platformSafeKey() は、単にスラッシュを先頭に付加するだけです。Apple オペレーティングシステムでは、これらの関数は結果を許容サイズに切り詰めます。

Windows

Windows のキータイプは NTカーネルオブジェクト名であり、長さは最大MAX_PATH (260) 文字まで可能です。これらは相対パスのように見えます（つまり、バックスラッシュやドライブ文字で始まらない）が、Windows のファイル名とは異なり、大文字と小文字が区別されます。

以下は、ネイティブな Windows キーの良い例です。「myapp」、「org.example.myapp」、「org.example.myapp-12345」。

QSharedMemory::platformSafeKey() および QSystemSemaphore::platformSafeKey() は、それぞれ共有メモリとシステムセマフォを区別するためにプレフィックスを挿入します。

X/Open システムインターフェース (XSI) / System V

System V キーは、システム上のファイル名の形式をとるため、ファイルパスとまったく同じ制限があります。QSharedMemory とQSystemSemaphore の両方は、オブジェクトの作成時にそのファイルが存在しない場合、そのファイルを作成します。 自動削除が無効になっている場合、このキーはQSharedMemory とQSystemSemaphore の間で競合することなく共有され、既存の任意のファイル（例えば、プロセス実行ファイルそのものでも可。QCoreApplication::applicationFilePath() を参照）を指定できます。現在のディレクトリの違いによる誤りを避けるため、パスは絶対パスである必要があります。

QSharedMemory::platformSafeKey() および QSystemSemaphore::platformSafeKey() は、常に絶対パスを返します。入力がすでに絶対パスである場合は、その入力を変更せずに返します。それ以外の場合は、アプリケーションが通常ファイルを作成する権限を持つ適切なパスを先頭に付加して返します。

所有権

共有メモリとシステムセマフォのオブジェクトは、使用前に作成する必要があります。これは、それぞれQSharedMemory::create()を使用するか、コンストラクタにQSystemSemaphore::Create を渡すことで行われます。

Unix システムでは、オブジェクトを作成した Qt クラスが、当該オブジェクトのクリーンアップを担当します。 したがって、その C++ オブジェクトを使用しているアプリケーションが不正常に終了した場合（クラッシュ、qFatal() の呼び出しなど）、オブジェクトが残される可能性があります。その場合、アプリケーションはオブジェクトを再度作成できない可能性があるため、代わりに既存のオブジェクトにアタッチする必要があります。たとえば、QSharedMemory の場合：

if (!shm.create(4096) && shm.error() == QSharedMemory::AlreadyExists)
    shm.attach();

QSystemSemaphore への再アタッチはおそらく賢明ではありません。その中のトークンカウンタは未知の状態にある可能性が高く、その結果、デッドロックを引き起こす恐れがあるためです。

POSIX リアルタイム

POSIX リアルタイムオブジェクトの所有権は、ファイルと同様の仕組みを採用しており、使用中のプロセスとは無関係に存在します。Qt ではオブジェクトがまだ使用中であるかどうかを判断できないため、自動削除によってその場合でもオブジェクトが削除されてしまいます。これにより、同じオブジェクトへのアタッチは不可能になりますが、既存のアタッチメントには影響しません。

Qt 6.6 以前では、QNX を除き、Qt は POSIX リアルタイムオブジェクトをクリーンアップすることはありませんでした。

X/Open システムインターフェース (XSI) / System V

Qt XMLクラスによって管理されるリソースは 2 つあります。キーが参照するファイルと、オブジェクトそのものです。QSharedMemory は、オブジェクトを協調的に管理します。つまり、最後のアタッチメントがオブジェクトそのものを削除し、その後キーファイルを削除する責任を負います。QSystemSemaphore は、QSystemSemaphore::Create が渡された場合にのみオブジェクトを削除します。さらに、そのオブジェクトがキーファイルを作成した場合は、そのファイルも削除します。

Qt 6.6 以降、どちらのクラスに対してもクリーンアップを行わないよう指定することが可能になりました。

Windows

オペレーティングシステムがオブジェクトを所有しており、オブジェクトへの最後のハンドルが閉じられた後にクリーンアップを行います。

古い Qt アプリケーションとの相互運用性

QNativeIpcKey クラスはQt 6.6で導入されました。このバージョン以前は、QSharedMemory およびQSystemSemaphore バックエンドは、Qt自身のビルド時に決定されていました。Windowsシステムの場合、常にWindowsバックエンドが使用されていました。 Unixシステムの場合、設定スクリプトによって利用可能であると判断された場合は、デフォルトでSystem Vバックエンドが使用されました。利用できない場合は、POSIXバックエンドにフォールバックしていました。POSIXバックエンドは、Qtのconfigureスクリプトに対して-feature-ipc_posix オプションを指定することで明示的に選択することができ、これが有効に設定されている場合、QT_POSIX_IPC マクロが定義されていました。

Qt 6.6 では、この configure スクリプトのオプションは残されていますが、バックエンドの利用可否を制御することはなくなりました。その代わりに、QNativeIpcKey::legacyDefaultTypeForOs() が返す値を変更するようになりました。互換性を維持する必要があるアプリケーションは、相互運用性を保証するために、このキー型のみを使用する必要があります。

QSharedMemory およびQSystemSemaphore の両方の API には、クロスプラットフォームキーという概念がありましたが、これは現在非推奨となっており、代わりに QSharedMemory::legacyNativeKey() および QSystemSemaphore::legacyNativeKey() を使用することが推奨されています。これら 2 つの関数は、以前のバージョンで非推奨となった関数と同じネイティブキーを生成します。 例えば、古いコードが次のようなものであった場合：

QSharedMemory shm("org.example.myapplication");
QSystemSemaphore sem("org.example.myapplication");

次のように更新できます:

QSharedMemory shm(QSharedMemory::legacyNativeKey("org.example.myapplication"));
QSystemSemaphore sem(QSystemSemaphore::legacyNativeKey("org.example.myapplication"));

2つのアプリケーション間でネイティブキーのやり取りを行っていた場合、次のようなコードを更新する必要はありません:

QSharedMemory shm;
shm.setNativeKey(key);

ただし、古いアプリケーションがネイティブキーを受け入れていた場合、新しいアプリケーションでは、platformSafeKey() の2番目の引数にQNativeIpcKey::legacyDefaultTypeForOs()を指定して使用することも可能です。

X/Open システムインターフェース (XSI) / System V

QSharedMemory のキーには既存のファイルを決して使用しないでください。古いQtアプリケーションがそれを削除しようとする可能性があるためです。代わりに、QSharedMemory に作成させましょう。

Qt以外のアプリケーションとの相互運用性

Qt以外のアプリケーションとの相互運用性は、いくつかの制限付きで可能です:

• 共有メモリセグメントの作成時に競合が発生してはなりません
• QSharedMemory セグメントのロック機能は利用できません

非Qtアプリケーションとの通信は、常にネイティブキーを介して行わなければなりません。

QSharedMemory は常にセグメント全体をメモリにマッピングします。非Qtアプリケーションは、悪影響を及ぼすことなく、その一部のみをメモリにマッピングすることを選択できます。

POSIX リアルタイム

POSIX 共有メモリはshm_open()を使用して開き、POSIX システムセマフォはsem_open() を使用して開くことができます。

これらの関数はどちらも、QNativeIpcKey::nativeKey() の結果であり、QFile::encodeName() またはQFile::decodeName() を使用してファイル名用にエンコードされたname パラメータを受け取ります。

Windows

Windowsの共有メモリオブジェクトはCreateFileMappingWを使用して開き、WindowsのシステムセマフォオブジェクトはCreateSemaphoreWを使用して開くことができます。両関数の名前は「Create」で始まりますが、既存のオブジェクトにアタッチすることも可能です。

これらの関数に対するlpName パラメータは、変換を行わないQNativeIpcKey::nativeKey()の結果です。

外部アプリケーションがこれらの関数の非 Unicode バージョン（末尾が「A」の関数）を使用している場合、QString を使用して、名前を 8 ビット形式に変換したり、8 ビット形式から元の形式に変換したりすることができます。

X/Open システムインターフェース (XSI) / System V

System V 共有メモリはshmget()を使用して取得でき、System V システムセマフォはsemget() を使用して取得できます。

これらの関数のいずれにも指定するkey パラメータは、QNativeIpcKey::nativeKey() から取得したファイル名に、id として 81 または 0x51 (ASCII 大文字の 'Q') を指定してftok()関数を呼び出した結果です。

System V セマフォオブジェクトには複数のセマフォが含まれている場合がありますが、QSystemSemaphore は最初のセマフォ（sem_num では番号 0）のみを使用します。

QSharedMemory とQSystemSemaphore は、どちらも、最後のアタッチメントである場合、デフォルトで、IPC_RMID 操作を使用して、それぞれshmctl() およびsemctl() へオブジェクトを削除します。