FBB::Flock(3bobcat)

(Un)Locks access to files
(libbobcat-dev_6.12.00)

2005-2026

NAME

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

SYNOPSIS

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

DESCRIPTION

When multiple programs need to access the same information (e.g., on files or in shared memory) then accessing that information should be synchronized. While multiple programs can read the information in parallel, only one program should be allowed to write/modify the information to avoid data corruption. The class FBB::Flock allows program to synchronize reading/writing to files by locking access to an existing (or newly created) lock file. Locking can be exclusive, in which case only one program can access the information (commonly used when writing information), or shared, in which case multiple programs can access the information (commonly used when reading information).

Using Flock's locking facilities is comparable to using mutexes by multi-threaded programs: if programs (or threads of multi-threaded programs) do not use locking facilities then those programs (or threads) can break the data's integrity. Consequently multiple programs accessing the same information should use locking.

NAMESPACE

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

INHERITS FROM

CONSTRUCTORS

Flock():
The default constructor initializes a Flock object. The object cannot yet offer synchronization facilities since no lock file has been defined. See also the member setFilename below.

Flock(std::string filename, mode_t mode = 0600):
This constructor initializes a an Flock object using filename as its lock file. Multiple programs can specify the same file name, allowing them to synchronize their read/write actions. If filename does not already exist it is created using access mode mode. Merely constructing a Flock object does not activate locking. To (un)lock member functions are available (see below). )

Copy and move constructors (and assignment operators) are not available.

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

MEMBER FUNCTIONS

Requesting a shared lock succeeds if no other program has obtained an exclusive lock. Requesting an exclusive lock succeeds if not other program has obtained eithr a shared or an exclusive lock.

int fd() const:
The file descriptor associated with the current lock file is returned. If no lock file has been specified -1 is returned.
std::string const &filename() const:
The name of the lock file is returned. If no lockfile has been specified an empty string is returned.
void exclusive() const:
This member returns once the program has obtained an exclusive lock.
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. E.g., exclusive(4s) waits for at most four seconds to obtain a exclusive lock.
An exception is thrown if no lock file was specified.
void setFilename(std::string const filename):
The FBB::Flock objects uses filename as its lock file name. If the object has currently acquired a lock it is released. 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

    #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

BUGS

None Reported.

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).