QSharedMemory 类

QSharedMemory 类提供对共享内存段的访问。更多...

头：	#include <QSharedMemory>
CMake:	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake:	QT += core
继承：	QObject

所有成员列表，包括继承成员

公共类型

enum	AccessMode { ReadOnly, ReadWrite }
enum	SharedMemoryError { NoError, PermissionDenied, InvalidSize, KeyError, AlreadyExists, …, UnknownError }

公共函数

	QSharedMemory (const QString & key , QObject * parent = nullptr)
	QSharedMemory (QObject * parent = nullptr)
	QSharedMemory (const QNativeIpcKey & key , QObject * parent = nullptr)
virtual	~QSharedMemory ()
bool	attach (QSharedMemory::AccessMode mode = ReadWrite)
const void *	constData () const
bool	create (qsizetype size , QSharedMemory::AccessMode mode = ReadWrite)
void *	data ()
const void *	data () const
bool	detach ()
QSharedMemory::SharedMemoryError	error () const
QString	errorString () const
bool	isAttached () const
QString	key () const
bool	lock ()
`(从 6.6 起)` QNativeIpcKey	nativeIpcKey () const
QString	nativeKey () const
void	setKey (const QString & key )
`(从 6.6 起)` void	setNativeKey (const QNativeIpcKey & key )
void	setNativeKey (const QString & key , QNativeIpcKey::Type type = QNativeIpcKey::legacyDefaultTypeForOs())
qsizetype	size () const
bool	unlock ()

详细描述

QSharedMemory 提供访问共享内存段通过多线程和多进程。共享内存段由 Key 标识，表示通过 QNativeIpcKey 。可以按跨平台方式创建 Key，通过使用 platformSafeKey()。

每个 QSharedMemory 对象必须 create () 段且这会调用指定段大小。所有其它进程只需 attach () 到必须已存在的段。2 操作成功后，应用程序可以调用 data () 以获得数据指针。

为支持非原子操作，QSharedMemory 提供 API 来获得独占访问：可以锁定共享内存采用 lock () 在读写共享内存前，但记住要释放锁采用 unlock () 在完成后。

默认情况下，QSharedMemory 会自动销毁共享内存段，当 QSharedMemory 的最后一个实例 detached 从段，且没有保留对段的引用。

有关 Key 类型、特定平台局限性、及与旧 (或非 Qt) 应用程序互操作的细节，见本机 IPC (进程间通信) 键文档编制。这包括 Apple 平台沙盒应用程序的重要信息，包括凭借 Apple APP 商店获得的所有应用。

另请参阅 进程间通信 and QSystemSemaphore .

成员类型文档编制

enum QSharedMemory:: AccessMode

常量	值	描述
`QSharedMemory::ReadOnly`	`0`	共享内存段是只读的。不允许写入共享内存段。尝试写入采用 ReadOnly 创建的共享内存段，会导致程序中止。
`QSharedMemory::ReadWrite`	`1`	允许读写共享内存段。

enum QSharedMemory:: SharedMemoryError

常量	值	描述
`QSharedMemory::NoError`	`0`	没有出现错误。
`QSharedMemory::PermissionDenied`	`1`	操作失败，因为调用者没有所需权限。
`QSharedMemory::InvalidSize`	`2`	创建操作失败，因为请求大小无效。
`QSharedMemory::KeyError`	`3`	操作失败，因为键无效。
`QSharedMemory::AlreadyExists`	`4`	A create () 操作失败，因为具有指定键的共享内存段已存在。
`QSharedMemory::NotFound`	`5`	An attach () 失败，因为找不到具有指定键的共享内存段。
`QSharedMemory::LockError`	`6`	试图 lock () 共享内存段失败，因为 create () 或 attach () 失败和返回 false，或因为发生系统错误在 QSystemSemaphore::acquire ().
`QSharedMemory::OutOfResources`	`7`	A create () 操作失败，因为没有足够内存可用于填充请求。
`QSharedMemory::UnknownError`	`8`	发生其它事情且很糟糕。

成员函数文档编制

QSharedMemory:: QSharedMemory (const QString & key , QObject * parent = nullptr)

构造共享内存对象采用给定 parent 和采用将遗留键设为 key 。因为有设置键，其 create () 和 attach () 函数可以被调用。

另请参阅 setKey (), create ()，和 attach ().

QSharedMemory:: QSharedMemory ( QObject * parent = nullptr)

此函数重载 QSharedMemory()。

构造共享内存对象采用给定 parent 。由于构造函数未设置共享内存对象的键，因此，共享内存对象没有附加底层共享内存段。必须设置键采用 setNativeKey () 先于 create () 或 attach () 可以使用。

另请参阅 setNativeKey ().

QSharedMemory:: QSharedMemory (const QNativeIpcKey & key , QObject * parent = nullptr)

这是重载函数。

构造共享内存对象采用给定 parent 并将其键设为 key 。因为有设置键，其 create () 和 attach () 函数可以被调用。

另请参阅 setNativeKey (), create ()，和 attach ().

`[virtual noexcept]` QSharedMemory:: ~QSharedMemory ()

析构函数清零键，强制共享内存对象 detach 从其底层共享内存段。若此共享内存对象是连接到共享内存段的最后一个， detach () 操作会销毁共享内存段。

另请参阅 detach () 和 isAttached ().

bool QSharedMemory:: attach ( QSharedMemory::AccessMode mode = ReadWrite)

试图将进程附加到共享内存段，通过传递给构造函数的键标识或调用 setNativeKey ()。访问 mode is ReadWrite 默认情况下。它还可以为 ReadOnly 。返回 true 若附加操作成功。若返回 false，调用 error () 以确定发生何种错误。在附加共享内存段后，可以获得共享内存的指针通过调用 data ().

另请参阅 isAttached (), detach ()，和 create ().

const void *QSharedMemory:: constData () const

返回的 const 指针指向共享内存段的内容，若有附加的话。否则，返回 null。由此函数返回的值不会改变，直到 detach 发生，所以存储此指针是安全的。

若内存操作不是原子的，可以锁定共享内存采用 lock () 先于读写，但记住要释放锁采用 unlock () 在完成后。

另请参阅 attach () 和 create ().

bool QSharedMemory:: create ( qsizetype size , QSharedMemory::AccessMode mode = ReadWrite)

创建共享内存段 size 个字节采用传递给构造函数的 Key 或设置采用 setNativeKey ()，然后附加到新共享内存段采用给定访问 mode 并返回 true 。若由键标识的共享内存段已存在，不履行附加操作和 false 被返回。当返回值为 false ，调用 error () 以确定发生何种错误。

另请参阅 error ().

void *QSharedMemory:: data ()

返回的指针指向共享内存段的内容，若有附加的话。否则，返回 null。由此函数返回的值不会改变，直到 detach 发生，所以存储此指针是安全的。

若内存操作不是原子的，可以锁定共享内存采用 lock () 先于读写，但记住要释放锁采用 unlock () 在完成后。

另请参阅 attach ().

const void *QSharedMemory:: data () const

此函数重载 data()。

bool QSharedMemory:: detach ()

从共享内存段分离进程。若这是附加到共享存储段的最后进程，则共享存储段由系统释放 (即：销毁内容)。函数返回 true 若它分离了共享内存段。若它返回 false ，通常意味着段未被附加或被另一进程锁定。

另请参阅 attach () 和 isAttached ().

QSharedMemory::SharedMemoryError QSharedMemory:: error () const

返回指示是否发生错误的值，且若如此，指示错误是什么。

另请参阅 errorString ().

QString QSharedMemory:: errorString () const

返回最后发生错误的文本描述。若 error () 返回错误值，调用此函数以获取描述错误的文本字符串。

另请参阅 error ().

bool QSharedMemory:: isAttached () const

返回 true 若此进程被附加到共享内存段。

另请参阅 attach () 和 detach ().

QString QSharedMemory:: key () const

返回的遗留键赋值采用 setKey () 到此共享内存，或 null 键若尚未赋值键，或段使用的是 nativeKey ()。键是 Qt 应用程序用来标识共享内存段的标识符。

可以找到由操作系统使用的本机、特定平台键，通过调用 nativeKey ().

另请参阅 setKey () 和 setNativeKey ().

bool QSharedMemory:: lock ()

这是锁供此进程访问的共享内存段的信号量，并返回 true 。若另一进程已锁定段，此函数阻塞直到锁被释放为止。然后，获取锁并返回 true 。若此函数返回 false ，意味着已忽略的 false 返回来自 create () 或 attach ()，已设置键采用 setNativeKey () 或 QSystemSemaphore::acquire () 失败由于未知系统错误。

另请参阅 unlock (), data ()，和 QSystemSemaphore::acquire ().

`[since 6.6]` QNativeIpcKey QSharedMemory:: nativeIpcKey () const

返回用于此共享内存对象的键类型。键类型互补 nativeKey () 作为 OS (操作系统) 用来标识共享内存段的标识符。

可以使用本机键访问 Qt 尚未创建的共享内存段，或将共享内存访问授予非 Qt 应用程序。见本机 IPC (进程间通信) 键了解更多信息。

该函数在 Qt 6.6 引入。

另请参阅 nativeKey () 和 setNativeKey ().

QString QSharedMemory:: nativeKey () const

返回用于此共享内存对象的本机、特定平台键。本机键是操作系统用于标识共享内存段的标识符。

可以使用本机键访问 Qt 尚未创建的共享内存段，或将共享内存访问授予非 Qt 应用程序。见本机 IPC (进程间通信) 键了解更多信息。

另请参阅 setNativeKey () 和 nativeIpcKey ().

void QSharedMemory:: setKey (const QString & key )

这是重载函数。

设置遗留 key 为此共享内存对象。若 key 与当前键相同，函数返回不做任何事情。否则，若有附加共享内存对象到底层共享内存段，它将 detach 从其，在设置新键之前。此函数不做 attach ().

可以调用 key () 以检索遗留 Key。此函数主要如同：

shm.setNativeKey(QSharedMemory::legacyNativeKey(key));

除了使之能够获取遗留 Key 使用 key ().

另请参阅 key (), nativeKey ()，和 isAttached ().

`[since 6.6]` void QSharedMemory:: setNativeKey (const QNativeIpcKey & key )

设置特定平台本机 key 为此共享内存对象。若 key 与当前本机键相同，函数返回不做任何事情。否则，若有附加共享内存对象到底层共享内存段，它将 detach 从其，在设置新键之前。此函数不做 attach ().

此函数很有用，若本机键共享来自另一进程。见本机 IPC (进程间通信) 键了解更多信息。

使用 platformSafeKey() 可以获得可移植本机 Key。

可以调用 nativeKey () 来检索本机键。