QSharedMemory Class

The QSharedMemory class provides access to a shared memory segment. More…

Header	`#include <QSharedMemory>`
CMake	`target_link_libraries(app PRIVATE Nt::Core)`
Module	Nt Core C++ Classes
Inherits	QObject

List of all members, including inherited members

Public Types

enum	AccessMode
enum	SharedMemoryError

Public Functions

	QSharedMemory(QObject *parent = nullptr)
	QSharedMemory(const QString &key, QObject *parent = nullptr)
	~QSharedMemory()
void	setKey(const QString &key)
QString	key() const
void	setNativeKey(const QString &key)
QString	nativeKey() const
bool	create(qsizetype size, AccessMode mode = ReadWrite)
qsizetype	size() const
bool	attach(AccessMode mode = ReadWrite)
bool	isAttached() const
bool	detach()
void *	data()
const void *	constData() const
const void *	data() const
bool	lock()
bool	unlock()
SharedMemoryError	error() const
QString	errorString() const

Detailed Description

A shared memory segment is memory that several processes see, found by its key. One process creates the segment with create(); the others attach() to it. Each then reads and writes the same bytes through data(). As the processes run at the same time, they take the lock of the segment around every access:

QSharedMemory memory(u"org.example.frame"_s);
if (!memory.create(1024) && !memory.attach())
    return;
memory.lock();
std::memcpy(memory.data(), frame, 1024);
memory.unlock();

The segment is removed from the system when the last object that is attached to it detaches, which the destructor does. A process that crashes does not detach, and its segment stays; a process that then attaches to the key and detaches again removes it.

See also QSystemSemaphore.

Differences from Qt

The segment is POSIX shared memory, so the class works on Linux and macOS, and a process cannot find a segment that another library made with a System V key. The native key is the name of the POSIX object, such as /name. There is no QNativeIpcKey, and so no constructor that takes one and no nativeIpcKey(). The lock is a file lock on the segment where the system has locks that belong to an open file, as Linux does, and a system semaphore elsewhere: with the file lock, lock() needs the object to be attached, and the lock of a process that dies is released. create(), attach() and detach() do not take the lock themselves.

The class is not built for Zephyr, where QT_NO_SHAREDMEMORY is defined instead. See Nt on Zephyr.

Member Type Documentation

enum QSharedMemory::AccessMode

What the process may do with the memory it attaches.

Constant	Description
`QSharedMemory::ReadOnly`	The memory can only be read. Writing to it ends the process.
`QSharedMemory::ReadWrite`	The memory can be read and written.

enum QSharedMemory::SharedMemoryError

The errors that error() reports.

Constant	Description
`QSharedMemory::NoError`	The last operation succeeded.
`QSharedMemory::PermissionDenied`	The process may not use the segment.
`QSharedMemory::InvalidSize`	The size given to create() is not a size a segment can have.
`QSharedMemory::KeyError`	The key is empty or cannot be used.
`QSharedMemory::AlreadyExists`	create() found a segment with the key.
`QSharedMemory::NotFound`	attach() found no segment with the key.
`QSharedMemory::LockError`	lock() or unlock() failed, or the object is attached already or not attached.
`QSharedMemory::OutOfResources`	The system has not enough memory for the segment.
`QSharedMemory::UnknownError`	Something else went wrong; errorString() has the text of the system.

Member Function Documentation

[explicit] QSharedMemory::QSharedMemory(QObject **parent* = nullptr)

Constructs a shared memory object with the given parent and no key.

See also setKey().

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

Constructs a shared memory object with the given parent for the segment key. Nothing is created or attached yet.

See also create() and attach().

[override] QSharedMemory::~QSharedMemory()

Destroys the object, after it has detached from the segment. The segment is removed from the system if no other object is attached to it.

bool QSharedMemory::attach(AccessMode mode = ReadWrite)

Attaches to the segment of the key, which another object created, with the access mode. Returns true on success. It fails, with error() set, if the object is attached already or there is no such segment.

See also create(), detach() and isAttached().

const void * QSharedMemory::constData() const

Returns a pointer to the first byte of the attached segment that cannot be written through, or nullptr if the object is not attached.

See also data().

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

Creates a segment of size bytes for the key and attaches to it with the access mode. The memory starts as zeros. Returns true on success. It fails, with error() set, if the object is attached already, the key is empty, size is not positive, or a segment with the key exists: then attach() to that one.

See also attach() and error().

void * QSharedMemory::data()

Returns a pointer to the first byte of the attached segment, or nullptr if the object is not attached. Take the lock() before using the memory.

See also constData() and size().

const void * QSharedMemory::data() const

This is an overloaded function.

bool QSharedMemory::detach()

Detaches from the segment, after which data() is nullptr. If no other object is attached, the segment is removed from the system. Returns false if the object was not attached.

See also attach().

SharedMemoryError QSharedMemory::error() const

Returns what went wrong in the last operation, or NoError.

See also errorString().

QString QSharedMemory::errorString() const

Returns a text for the error of the last operation, or an empty string if it succeeded.

See also error().

bool QSharedMemory::isAttached() const

Returns true if the object is attached to a segment.

See also attach() and detach().

QString QSharedMemory::key() const

Returns the key that was set with setKey(), or an empty string if a native key was set.

See also setKey().

bool QSharedMemory::lock()

Takes the lock of the segment, waiting until no other object has it. Returns true when this object has the lock. It fails, with error() set, if this object has the lock already, is not attached, has no key, or the lock of the system cannot be used.

See also unlock().

QString QSharedMemory::nativeKey() const

Returns the name that the segment has in the system.

See also setNativeKey().

void QSharedMemory::setKey(const QString &key)

Sets the key of the object to key, after detaching from the segment it is attached to. The key can be any text; the name of the segment in the system is made from it.

See also key() and nativeKey().

void QSharedMemory::setNativeKey(const QString &key)

Sets the name of the segment in the system to key, after detaching from the segment the object is attached to. Use this to share memory with a program that does not use this class.

See also nativeKey().

qsizetype QSharedMemory::size() const

Returns the size of the attached segment in bytes, or 0 if the object is not attached.

See also create().

bool QSharedMemory::unlock()

Gives the lock of the segment back. Returns false if this object does not have it.

See also lock().