FBB::Flock(3bobcat)

📦
version 6.15.01 · 2 versions
, in ubuntu stonking

💖 FBB::Flock 💖

okay bestie, welcome to the FBB::Flock page — that's section 3 of the bobcat manual, in case you were wondering where we are 🦋. Buckle up, because this one is literally about stopping your programs from stepping on each other's toes.

✨ NAME ✨

FBB::Flock — allows multiple programs to synchronize access to the information they use 💅

✨ SYNOPSIS ✨

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

✨ DESCRIPTION ✨

so like, imagine a bunch of programs all need the same info — could be files, could be shared memory, whatever. That access has to be synchronized, no cap. Multiple programs reading in parallel? Totally fine, slay. But the second more than one program wants to write/modify that info, it's giving chaos — data corruption era. 🙈

The class FBB::Flock lets programs synchronize reading/writing to files by locking access to a lock file that either already exists or gets created on the spot. Locking comes in two flavours:

  • Exclusive — only ONE program can access the info. This is the usual vibe when writing.
  • Shared — multiple programs can access the info. This is the usual vibe when reading.

ngl, using Flock's locking facilities is basically the same energy as using mutexes in multi-threaded programs: if programs (or threads of multi-threaded programs) don't use locking facilities, then those programs (or threads) can absolutely break the data's integrity. So yeah — multiple programs touching the same information should be locking. Periodt. 👑

✨ NAMESPACE ✨

FBB

Every constructor, member, operator and manipulator mentioned in this man-page is defined in the namespace FBB. iykyk 🫶

✨ INHERITS FROM ✨

-

(nothing bestie, it's a free agent 💅)

✨ CONSTRUCTORS ✨

  • Flock() — the default constructor initializes a Flock object. It can't offer you any synchronization facilities yet because no lock file has been defined. See also the member setFilename below. 🎀
  • Flock(std::string filename, mode_t mode = 0600) — this constructor initializes a Flock object using filename as its lock file. Multiple programs can specify the same file name, which is how they get to synchronize their read/write actions. If filename doesn't already exist, it gets created using access mode mode. And listen: merely constructing a Flock object does not activate locking. To (un)lock, there are member functions for that (see below). ✨
Copy and move constructors (and assignment operators) are not available. Not even a little bit. 💀

When an FBB::Flock object ceases to exist and the object has acquired a lock, then the FBB::Flock's destructor releases the lock. Cleanup queen. 🧚

✨ MEMBER FUNCTIONS ✨

Quick vibe check before we go through them:

  • Requesting a shared lock succeeds if no other program has obtained an exclusive lock.
  • Requesting an exclusive lock succeeds if no other program has obtained either a shared or an exclusive lock.

Got it? Good. Now the roster 🌸

  • int fd() const — returns the file descriptor associated with the current lock file. If no lock file has been specified, -1 is returned.
  • std::string const &filename() const — returns the name of the lock file. If no lock file has been specified, an empty string is returned.
  • void exclusive() const — this member returns once the program has obtained an exclusive lock. Just sits there patiently being iconic. 👑
  • bool exclusive(std::chrono::duration<Amount, Resolution> const &time) — returns true when an exclusive lock was obtained within time time units, otherwise false is returned. So like, exclusive(4s) waits for at most four seconds to obtain an exclusive lock. An exception is thrown if no lock file was specified.
  • void setFilename(std::string const filename) — the FBB::Flock object uses filename as its lock file name. If the object has currently acquired a lock, it is released. Heads up though: this member does not acquire a lock for filename. 🙈
  • void shared() const — this member returns once the program has obtained a shared lock.
  • bool shared(std::chrono::duration<Amount, Resolution> const &time) — returns true when a shared lock was obtained within time time units, otherwise false is returned. E.g. shared(4s) waits for at most four seconds to obtain a shared lock. An exception is thrown if no lock file was specified.
  • void unlock() const — this member releases the lock obtained by the Flock object. An exception is thrown if no lock file was specified.

✨ EXAMPLE ✨

here's the whole thing, verbatim, because slay:

#include <iostream>
c
#include <bobcat/flock>

using namespace std;
using namespace FBB;

int main(int argc, char **argv)
try
{
    if (argc < 3)
    {
        cerr << "need lockfile name and e or .\n";
        return 1;
    }

    Flock flock{ argv[1] };
    cout << "FD = " << flock.fd() << ’\n’;

    if (string str; *argv[2] == ’e’)
    {
        flock.exclusive();
        cout << "press Enter... ";
        getline(cin, str);
    }
    else
    {
        bool ok = flock.exclusive(3s);
        cout << "obtained a lock: " << ok << ’\n’;
        if (ok)
        {
            cout << "press Enter... ";
            getline(cin, str);
        }
    }
}
catch (...)
{
    cerr << "caught an exception\n";
}

✨ FILES ✨

  • bobcat/flock — defines the class interface 🎀

✨ SEE ALSO ✨

bobcat(7), flock(2), the std::chrono namespace 🌈

✨ BUGS ✨

None Reported. (we love a flawless queen 💅✨)

✨ BOBCAT PROJECT FILES ✨

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’. cute and clever, we love that for it 💜

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, you're officially Flock-pilled 🫶 this was libbobcat-dev_6.15.01, dated 2005-2026, and it's been giving FBB::Flock(3bobcat) realness the entire time. go lock something (responsibly), ily, bye 💅✨👑

📦 where this page comes from