内容

公共类型
公共函数
详细描述

QSharedMemory 类

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

头：	#include <QSharedMemory>
CMake:	find_package(Qt6 COMPONENTS Core REQUIRED) 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)
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 ()
QString	nativeKey () const
void	setKey (const QString & key )
void	setNativeKey (const QString & key )
qsizetype	size () const
bool	unlock ()

详细描述

QSharedMemory 提供对多线程和进程共享内存段的访问。它还为单线程 (或进程) 提供锁定内存的独占访问手段。

当使用此类时，要意识到以下平台差异：

Windows：QSharedMemory 不 "拥有" 共享内存段。当拥有 QSharedMemory 实例 (被附加到特定共享内存段) 的所有线程 (或进程) 销毁 QSharedMemory 实例 (或退出) 时，Windows 内核会自动释放共享内存段。
Unix：QSharedMemory "拥有" 共享内存段。当拥有 QSharedMemory 实例 (被附加到特定共享内存段) 的最后线程 (或进程) 通过销毁其 QSharedMemory 实例从段分离时，Unix 内核会释放共享内存段。但是，若最后线程 (或进程) 未运行 QSharedMemory 析构函数崩溃，共享内存段会在崩溃时幸存。
HP-UX：每进程只允许一个附加到共享内存段。这意味着不应该将 QSharedMemory 用于跨多个线程的同一 HP-UX 进程。
Apple platforms: Sandboxed applications (including apps shipped through the Apple App Store) require the use of POSIX shared memory (instead of System V shared memory), which adds a number of limitations, including:
- The key must be in the form <application group identifier>/<custom identifier> ，如文档化 here and here .
- The key length is limited to 30 characters.
- 当进程退出时，不会清理命名的共享内存条目，因此，重启应用程序并以相同名称重新创建共享内存会失败。要解决此问题，回退到附加现有共享内存条目：
```
QSharedMemory shm("DEVTEAMID.app-group/shared");
if (!shm.create(42) && shm.error() == QSharedMemory::AlreadyExists)
    shm.attach();
									
```

记住锁定共享内存采用 lock () 在读写共享内存之前，和记住释放锁采用 unlock () 在完成后。

QSharedMemory 自动销毁共享内存段，当从段分离最后 QSharedMemory 实例时，且不保留段引用。

警告： QSharedMemory 以特定 Qt 方式改变键，除非另外指定。与非 Qt 应用程序的互操作的达成是通过首先创建默认共享内存采用 QSharedMemory()，然后设置本机键采用 setNativeKey ()。当使用本机键时，不保护对共享内存的多次访问 (例如：无法 lock ()) 且应该使用用户定义机制来达成这种保护。

成员类型文档编制

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 。由于构造函数未设置共享内存对象的键，因此，共享内存对象没有附加底层共享内存段。必须设置键采用 setKey () 或 setNativeKey () 先于 create () 或 attach () 可以使用。

另请参阅 setKey ().

`[虚拟]` QSharedMemory:: ~QSharedMemory ()

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

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

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

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

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

const void *QSharedMemory:: constData () const

返回共享内存段内容的 const 指针，若有附加一个的话。否则，返回 null。记得锁定共享内存采用 lock () 在读写共享内存之前，和记住释放锁采用 unlock () 在完成后。

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

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

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

另请参阅 error ().

void *QSharedMemory:: data ()

另请参阅 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 ().

QString QSharedMemory:: nativeKey () const

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

可以使用本机键访问 Qt 尚未创建的共享内存段，或将共享内存访问授予非 Qt 应用程序。

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

void QSharedMemory:: setKey (const QString & key )

设置平台无关 key 为此共享内存对象。若 key 与当前键相同，函数将什么都不做而返回。

可以调用 key () 以检索平台无关键。在内部， QSharedMemory 将此键转换成平台特定键。若改为调用 nativeKey ()，将获得特定平台的转换键。

若将共享内存对象附加到底层共享内存段，它将 detach 从其，在设置新键之前。此函数不做 attach ().

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

void QSharedMemory:: setNativeKey (const QString & key )

设置特定平台本机 key 为此共享内存对象。若 key 与当前本机键相同，函数将什么都不做而返回。若只想为段赋值键，应调用 setKey () 代替。

可以调用 nativeKey () 以检索本机键。若有赋值本机键，调用 key () 将返回 null 字符串。