includefile(include/header)

COMMENT(replace 'classname' by the name of the new class)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Flock)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
       ((Un)Locks access to files)

manpagename(FBB::Flock)(
    allows multiple programs to synchronize access to the information they
        use)

manpagesynopsis()
    bf(#include <bobcat/classname>)nl()
    Linking option: tt(-lpthread -lbobcat)

manpagedescription()
    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 bf(FBB::Flock) allows program to synchronize
reading/writing to files by locking access to an existing (or newly created)
lock file. Locking can be em(exclusive), in which case only one program can
access the information (commonly used when writing information), or
em(shared), in which case multiple programs can access the information
(commonly used when reading information).

    Using bf(Flock)'s locking facilities is comparable to using em(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.

includefile(include/namespace)

manpagesection(INHERITS FROM)
    -

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

    itb(Flock(std::string filename, mode_t mode = 0600))
       This constructor initializes a an bf(Flock) object using tt(filename)
        as its lock file. Multiple programs can specify the same file name,
        allowing them to synchronize their read/write actions. If tt(filename)
        does not already exist it is created using access mode
        tt(mode). Merely constructing a bf(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 bf(FBB::Flock) object ceases to exist and the object has acquired
    a lock then the bf(FBB::Flock)'s destructor releases the lock.

manpagesection(MEMBER FUNCTIONS)

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

    itemization(
    itb(int fd() const)
       The file descriptor associated with the current lock file is
        returned. If no lock file has been specified -1 is returned.

    itb(std::string const &filename() const)
       The name of the lock file is returned. If no lockfile has been
        specified an empty string is returned.

    itb(void exclusive() const)
       This member returns once the program has obtained an exclusive lock.

    itb(bool exclusive(std::chrono::duration<Amount, Resolution> const &time))
       Returns tt(true) when an exclusive lock was obtained within tt(time)
        time units, otherwise tt(false) is returned. E.g., tt(exclusive(4s))
        waits for at most four seconds to obtain a exclusive lock.nl()
       An exception is thrown if no lock file was specified.

    itb(void setFilename(std::string const filename))
       The bf(FBB::Flock) objects uses tt(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 tt(filename).

    itb(void shared() const)
        This member returns once the program has obtained a shared lock.

    itb(bool shared(std::chrono::duration<Amount, Resolution> const &time))
       Returns tt(true) when a shared lock was obtained within tt(time) time
        units, otherwise tt(false) is returned. E.g., tt(shared(4s)) waits for
        at most four seconds to obtain a shared lock.nl() 
       An exception is thrown if no lock file was specified.

    itb(void unlock() const)
       This member releases the lock obtained by the tt(Flock) object.nl() 
       An exception is thrown if no lock file was specified.
    )

manpagesection(EXAMPLE)
    verbinsert(-as4 ../../flock/driver/driver.cc)

manpagefiles()
    em(bobcat/flock) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(flock)(2), the tt(std::chrono) namespace

manpagebugs()
    None Reported.

includefile(include/trailer)


