Clés IPC natives

Les classes QSharedMemory et QSystemSemaphore identifient leur ressource à l'aide d'un identifiant à l'échelle du système appelé "clé". La valeur de la clé de bas niveau ainsi que le type de clé sont encapsulés dans Qt XML à l'aide de la classe QNativeIpcKey. Cette classe fournit également les moyens appropriés pour échanger la clé avec d'autres processus, par le biais de QNativeIpcKey::toString() et QNativeIpcKey::fromString().

Qt supporte actuellement trois backends distincts pour ces deux classes, qui correspondent aux valeurs disponibles dans l'énumération QNativeIpcKey::Type.

• POSIX Realtime extensions (IEEE 1003.1b, POSIX.1b)
• X/Open System Interfaces (XSI) ou System V (SVr4), bien qu'ils fassent désormais partie de POSIX.
• Primitives Windows

Comme leur nom l'indique, les primitives Windows ne sont disponibles que sur le système d'exploitation Windows, où elles constituent le backend par défaut. Les deux autres sont généralement disponibles sur les systèmes d'exploitation Unix. Le tableau suivant donne un aperçu de la disponibilité typique depuis Qt 6.6 :

Pour déterminer si un type de clé donné est pris en charge, les applications doivent appeler QSharedMemory::isKeyTypeSupported() et QSystemSemaphore::isKeyTypeSupported().

QNativeIpcKey QSharedMemory::isKTypeSupported() et QSystemSemaphore::isKTypeSupported(). Les sections suivantes détaillent les limitations des backends, le contenu des clés de chaîne elles-mêmes et la compatibilité.

Format de clé sûr multiplateforme

QNativeIpcKey::setNativeKey() et QNativeIpcKey::nativeKey() gèrent la clé native de bas niveau, qui peut être utilisée avec les API natives et partagée avec d'autres processus non Qt (voir ci-dessous pour l'API). Ce format n'est généralement pas multiplateforme, c'est pourquoi QSharedMemory et QSystemSemaphore fournissent une fonction permettant de traduire une chaîne d'identification multiplateforme en clé native : QSharedMemory::platformSafeKey() et QSystemSemaphore::platformSafeKey().

La longueur de la clé multiplateforme sur la plupart des plateformes est la même que celle d'un nom de fichier, mais elle est sévèrement limitée sur les plateformes Apple à seulement 30 octets utilisables (attention à l'encodage UTF-8 si vous utilisez des caractères en dehors de la gamme US-ASCII). Le format de la clé est également similaire à celui d'un composant de chemin d'accès, ce qui signifie qu'elle ne doit pas contenir de caractères non autorisés dans les noms de fichiers, en particulier ceux qui séparent les composants de chemin d'accès (barre oblique et barre oblique inverse), à l'exception des applications en bac à sable sur les systèmes d'exploitation Apple. Les exemples suivants sont de bons exemples de clés multiplateformes : "myapp", "org.example.myapp", "org.example.myapp-12345". Notez que c'est à l'appelant d'éviter les clés surdimensionnées, et de s'assurer que la clé contient des caractères légaux sur la plateforme respective. Qt tronquera silencieusement les clés trop longues.

Limitations du bac à sable d'Apple : si l'application fonctionne dans un bac à sable d'un système d'exploitation Apple, la clé doit être dans un format très spécifique : <application group identifier>/<custom identifier>. Le sandboxing est implicite pour toutes les applications distribuées par l'Apple App Store. Voir la documentation d'Apple ici et ici pour plus d'informations, notamment sur la manière d'obtenir l'identifiant de groupe de l'application.

Format de la clé native

Cette section détaille le format des clés natives des backends pris en charge.

POSIX temps réel

Les clés natives ressemblent à des noms de fichiers et peuvent contenir tous les caractères des noms de fichiers, à l'exception d'une barre oblique. POSIX exige que le premier caractère du nom de la clé soit une barre oblique et ne détermine pas si d'autres barres obliques sont autorisées. Sur la plupart des systèmes d'exploitation, la longueur de la clé est la même que celle d'un nom de fichier, mais elle est limitée à 32 caractères sur les systèmes d'exploitation Apple (y compris la première barre oblique et le caractère nul de fin, de sorte que seuls 30 caractères utilisables sont possibles).

Les exemples suivants sont de bons exemples de clés POSIX natives : "/myapp", "/org.example.myapp", "/org.example.myapp-12345".

QSharedMemory::platformSafeKey() et QSystemSemaphore::platformSafeKey() ajoutent simplement la barre oblique. Sur les systèmes d'exploitation Apple, ils tronquent également le résultat à la taille disponible.

Windows

Les types de clés Windows sont des noms d'objets du noyau NT et peuvent contenir jusqu'à MAX_PATH (260) caractères. Ils ressemblent à des chemins relatifs (c'est-à-dire qu'ils ne commencent pas par une barre oblique inverse ou une lettre de lecteur), mais contrairement aux noms de fichiers sous Windows, ils sont sensibles à la casse.

Les exemples suivants sont de bons exemples de clés Windows natives : "myapp", "org.example.myapp", "org.example.myapp-12345".

QSharedMemory::platformSafeKey() et QSystemSemaphore::platformSafeKey() insèrent un préfixe pour désambiguïser la mémoire partagée et les sémaphores système, respectivement.

X/Open System Interfaces (XSI) / Système V

Les clés du système V prennent la forme du nom d'un fichier dans le système, et ont donc exactement les mêmes limitations que les chemins d'accès aux fichiers. QSharedMemory et QSystemSemaphore créeront ce fichier s'il n'existe pas lors de la création de l'objet. Si la suppression automatique est désactivée, il peut également être partagé entre QSharedMemory et QSystemSemaphore sans conflit et peut être n'importe quel fichier existant (par exemple, il peut s'agir de l'exécutable du processus lui-même, voir QCoreApplication::applicationFilePath()). Le chemin d'accès doit être absolu afin d'éviter les erreurs dues à des répertoires courants différents.

QSharedMemory::platformSafeKey() et QSystemSemaphore::platformSafeKey() renvoient toujours un chemin absolu. Si l'entrée était déjà absolue, ils renverront leur entrée inchangée. Sinon, elles ajouteront un chemin approprié dans lequel l'application a généralement le droit de créer des fichiers.

Propriété

Les objets de mémoire partagée et de sémaphore système doivent être créés avant d'être utilisés, ce qui est réalisé avec QSharedMemory::create() ou en passant QSystemSemaphore::Create au constructeur, respectivement.

Sur les systèmes Unix, les classes Qt qui ont créé l'objet seront responsables du nettoyage de l'objet en question. Par conséquent, si l'application contenant cet objet C++ se termine de manière impropre (crash, qFatal(), etc.), l'objet peut être laissé sur place. Dans ce cas, les applications peuvent ne pas créer l'objet à nouveau et doivent plutôt s'attacher à un objet existant. Par exemple, pour QSharedMemory:

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

Il n'est probablement pas judicieux de s'attacher à nouveau à une adresse QSystemSemaphore, car le compteur de jetons qu'elle contient est probablement dans un état inconnu et peut donc conduire à des blocages.

POSIX Realtime

La propriété des objets POSIX Realtime est calquée sur celle des fichiers, dans le sens où ils existent indépendamment de tout processus qui les utilise ou non. Qt n'est pas en mesure de déterminer si l'objet est toujours en cours d'utilisation, de sorte que la suppression automatique le supprimera même dans ce cas, ce qui rendra impossible l'attachement au même objet, mais n'affectera pas les attachements existants.

Avant Qt 6.6, Qt ne nettoyait jamais les objets POSIX Realtime, sauf sur QNX.

X/Open System Interfaces (XSI) / System V

Il y a deux ressources gérées par les classes Qt : le fichier auquel la clé fait référence et l'objet lui-même. QSharedMemory gère l'objet de manière coopérative : la dernière pièce jointe est responsable de la suppression de l'objet lui-même et ensuite de la suppression du fichier clé. QSystemSemaphore supprimera l'objet si et seulement s'il a été transmis à QSystemSemaphore::Create; de plus, s'il a créé le fichier clé, il le supprimera également.

Depuis Qt 6.6, il est possible de demander à l'une ou l'autre classe de ne pas nettoyer.

Fenêtres

Le système d'exploitation est propriétaire de l'objet et le nettoie après la fermeture de la dernière poignée de l'objet.

Interopérabilité avec les anciennes applications Qt

La classe QNativeIpcKey a été introduite dans Qt 6.6. Avant cette version, les backends QSharedMemory et QSystemSemaphore étaient déterminés au moment de la construction de Qt. Pour les systèmes Windows, il s'agissait toujours du backend Windows. Pour les systèmes Unix, il s'agissait par défaut du backend System V si le script de configuration déterminait qu'il était disponible. S'il n'était pas disponible, il revenait au système POSIX. Le backend POSIX pouvait être explicitement sélectionné en utilisant l'option -feature-ipc_posix du script de configuration de Qt XML ; s'il était activé, la macro QT_POSIX_IPC serait définie.

Qt 6.6 conserve l'option du script de configuration mais ne contrôle plus la disponibilité des backends. En revanche, elle modifie ce que QNativeIpcKey::legacyDefaultTypeForOs() renvoie. Les applications qui doivent rester compatibles doivent utiliser exclusivement ce type de clé pour garantir l'interopérabilité.

L'API dans QSharedMemory et QSystemSemaphore avait le concept d'une clé multiplateforme, qui est maintenant dépréciée en faveur de l'utilisation de QSharedMemory::legacyNativeKey() et QSystemSemaphore::legacyNativeKey(). Ces deux fonctions produisent la même clé native que les fonctions dépréciées dans les versions précédentes. Si l'ancien code était par exemple : QSystemSemaphore::legacyNativeKey()

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

Il peut être mis à jour :

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

Si les deux applications ont échangé des clés natives, il n'est pas nécessaire de mettre à jour le code tel que :

QSharedMemory shm;
shm.setNativeKey(key);

Toutefois, si l'ancienne application acceptait une clé native, la nouvelle pourrait choisir d'utiliser platformSafeKey() avec un second argument de QNativeIpcKey::legacyDefaultTypeForOs().

X/Open System Interfaces (XSI) / System V

N'utilisez jamais de fichiers existants pour les clés QSharedMemory, car l'ancienne application Qt pourrait tenter de les supprimer. Laissez plutôt QSharedMemory les créer.

Interopérabilité avec les applications non Qt

L'interopérabilité avec les applications non Qt est possible, avec certaines limitations :

• la création de segments de mémoire partagée ne doit pas être concurrentielle
• QSharedMemory la prise en charge du verrouillage du segment n'est pas disponible

La communication avec les applications non-Qt doit toujours se faire par le biais de la clé native.

QSharedMemory La clé native permet toujours d'afficher l'intégralité du segment dans la mémoire. L'application non-Qt peut choisir de ne mettre en mémoire qu'un sous-ensemble du segment, sans effet négatif.

Temps réel POSIX

La mémoire partagée POSIX peut être ouverte en utilisant shm_open() et les sémaphores du système POSIX peuvent être ouverts en utilisant sem_open().

Ces deux fonctions prennent un paramètre name qui est le résultat de QNativeIpcKey::nativeKey(), encodé pour les noms de fichiers avec QFile::encodeName() / QFile::decodeName().

Windows

Les objets de mémoire partagée Windows peuvent être ouverts à l'aide de CreateFileMappingW et les objets sémaphores du système Windows peuvent être ouverts à l'aide de CreateSemaphoreW. Bien que le nom de ces deux fonctions commence par "Create", elles peuvent s'attacher à des objets existants.

Le paramètre lpName de ces fonctions est le résultat de QNativeIpcKey::nativeKey(), sans transformation.

Si l'application étrangère utilise la version non-Unicode de ces fonctions (se terminant par "A"), le nom peut être converti de et vers 8 bits à l'aide de QString.

X/Open System Interfaces (XSI) / Système V

La mémoire partagée du système V peut être obtenue en utilisant shmget() et les sémaphores du système V peuvent être obtenus en utilisant semget().

Le paramètre key de l'une ou l'autre de ces fonctions est le résultat de la fonction ftok() lorsqu'on lui passe le nom de fichier obtenu par QNativeIpcKey::nativeKey() avec un id de 81 ou 0x51 (la lettre majuscule ASCII 'Q').

Les objets sémaphores du système V peuvent contenir plusieurs sémaphores, mais QSystemSemaphore n'utilise que le premier (numéro 0 pour sem_num).

QSharedMemory et QSystemSemaphore suppriment par défaut l'objet en utilisant l'opération IPC_RMID pour shmctl() et semctl() respectivement s'il s'agit de la dernière pièce jointe.