FBB::SharedMutex(3bobcat)

💖 FBB::SharedMutex — Mutex for shared memory 💖

okay bestie, buckle up, we're doing the bobcat manual pages and this one is literally about a mutex that lives inside shared memory. yes, the manual name is bobcat (that's the 3bobcat bit, iykyk) and it's serving pure synchronization realness. let's go ✨

---

🌸 NAME 🌸

FBB::SharedMutex — Mutex for shared memory

---

✨ SYNOPSIS ✨

#include <bobcat/sharedmutex>
Linking option: -lpthread, -lbobcat

---

🦋 DESCRIPTION 🦋

so shared memory can be used by multiple processes at once, right? and to synchronize access to that shared memory, you can define an FBB::SharedMutex inside a shared memory segment. SharedMutex objects let clients lock a shared memory segment before reading or writing its content. for example, the Bobcat class FBB::SharedSegment defines a SharedMutex in its shared memory segment. it's giving teamwork, it's giving coordination 💅

the SharedMutex class uses the facilities offered by the PThread library to implement (non recursive) shared memory locking. and if you need to force unlocking a (possibly) locked shared memory segment, its destructor can be called. emergency exit, but make it official.

⚠️ SharedMutex mutexes are non-recursive, which means deadlocks if their lock member is called twice from the same thread of execution without an intermediate call to unlock. if this causes concern, a variable can be defined indicating whether the lock has already been obtained. not me warning you twice about the same thing, but like, seriously bestie, don't double-lock. 💀

---

🎀 NAMESPACE 🎀

FBB

all constructors, members, operators and manipulators mentioned in this man-page are defined in the namespace FBB. periodt.

---

🌈 INHERITS FROM 🌈

-

(yeah. nothing. it's independent. main character energy, no ancestry needed 👑)

---

💜 CONSTRUCTORS, DESTRUCTOR 💜

• SharedMutex() — the default constructor initializes an FBB::SharedMutex object to a shared memory mutex (using the PTHREAD_PROCESS_SHARED attribute). since an FBB::SharedMutex object will normally be defined inside a shared memory segment, the object's memory is already available. in that case placement new should be used to call the constructor. e.g., if a shared memory segment is attached to the current process at d_shared, and an FBB::SharedMutex should be defined at d_shared's address, then the FBB::SharedMutex object can be initialized like this:

new (d_shared) FBB::SharedMutex;

⚠️ Caveat: when using placement new to initialize a SharedMutex make sure that the SharedMutex fits inside a block (i.e., shared.blockOffset() + sizeof(SharedMemory) < shared.dataSegmentSize()). if not, use seek to switch to an offset where this equality holds true, or simply use SharedMemory::create like this:

FBB::SharedMemory::create<FBB::SharedMutex>();

• ~SharedMutex() — the class's destructor releases all of the current process's nested shared memory segment locks. to destroy an FBB::SharedMutex object that has been constructed using the placement new operator use

d_sharedMutex->~SharedMutex();

(assuming SharedMutex *d_sharedMutex points to the location where placement new has previously initialized the FBB::SharedMutex object.)

copy and move constructors (and assignment operators) are not available. nope. not a thing. don't even try 🙈

---

🍓 MEMBER FUNCTIONS 🍓

• void lock() const — when returning from this member, the current process has locked the shared memory segment. note that SharedMutex objects are non-recursive.
• void unlock() const — the object's lock of the shared memory segment is released. this member can also be called if the SharedMutex's lock has not been obtained. (chill unlock, no lock required, it's fine 🫶)

---

🧚 PROTECTED MEMBER FUNCTION 🧚

• pthread_mutex_t *mutexPtr() — a pointer is returned to the pthread_mutex_t object used by the SharedMutex object;

---

🔥 EXAMPLE 🔥

this is the whole vibe, copied exactly, no cap:

#include <sys/types.h>
#include <signal.h>

#include <iostream>
#include <string>
#include <chrono>
#include <bobcat/fork>
#include <bobcat/semaphore>
#include <bobcat/sharedsegment>
#include <bobcat/sharedmutex>

using namespace std;
using namespace FBB;

class Wait: public Fork
{
    SharedSegment *d_shared;
    int d_id;
    SharedMutex *d_mutex;

    public:
        Wait();
        ~Wait();
        void childProcess() override;
        void parentProcess() override;
};

Wait::Wait()
:
    d_shared(SharedSegment::create(&d_id, 1, 100, 0700)),
    d_mutex(new (d_shared) SharedMutex)
{
    cout << "shared memory ID = " << d_id << ’\n’;
}

Wait::~Wait()
{
    d_mutex->~SharedMutex();
    SharedSegment::deleteSegment(d_id);
    cout << "deleted the shared memory\n";
}

void Wait::childProcess()
{
    Semaphore waiter{0};

    while (true)
    {
        waiter.wait_for(chrono::seconds(2));
        d_mutex->lock();
        cout << "child hello\n";
        d_mutex->unlock();
    }
}

void Wait::parentProcess()
{
    string line;
    do
    {
        cout << "press enter to allow the parent to locck\n";
        cin.ignore(100, ’\n’);
        d_mutex->lock();
        cout << "parent has the lock, press enter to continue "
                "(to end: some input)\n";
        getline(cin, line);
        d_mutex->unlock();
    }
    while (line.empty());

    kill(pid(), SIGTERM);
}

int main()
{
    Wait waiter;
    waiter.fork();
}

---

🌸 FILES 🌸

bobcat/sharedmutex — defines the class interface

---

⭐ SEE ALSO ⭐

bobcat(7) isharedstream(3bobcat), osharedstream(3bobcat), sharedblock(3bobcat), sharedcondition(3bobcat), sharedmemory(3bobcat), (e.g.,) pthread_mutex_init(3posix), sharedpos(3bobcat), sharedreadme(7bobcat), sharedsegment(3bobcat), sharedstream(3bobcat), sharedbuf(3bobcat)

---

💀 BUGS 💀

None Reported.

(iconic behaviour, honestly.)

---

🎀 BOBCAT PROJECT FILES 🎀

• https://fbb-git.gitlab.io/bobcat/: gitlab project page;

Debian Bobcat project files:

• libbobcat6: debian package containing the shared library, changelog and copyright note;
• libbobcat-dev: debian package containing the static library, headers, manual pages, and developer info;

---

👑 BOBCAT 👑

Bobcat is an acronym of `Brokken’s Own Base Classes And Templates’. 💅

---

🫶 COPYRIGHT 🫶

This is free software, distributed under the terms of the GNU General Public License (GPL).

---

🌈 AUTHOR 🌈

Frank B. Brokken (f.b.brokken@rug.nl).

---

okay that's the whole page bestie, and the cute little sign-off goes like this: this is libbobcat-dev version 6.07.01, dated 2005-2025, and the manual page is FBB::SharedMutex(3bobcat). love that for us 💖✨🎀🦋