Wrapper around struct flock used for advisory file locking in FileDescriptor. More...

#include <FileLock.hxx>

Inheritance diagram for cosmos::FileLock:

Public Types
enum class	Type : short { READ_LOCK = F_RDLCK , WRITE_LOCK = F_WRLCK , UNLOCK = F_UNLCK }

enum class	SeekDir : short { SET = SEEK_SET , CUR = SEEK_CUR , END = SEEK_END }

Public Member Functions
	FileLock (const Type type, const SeekDir dir=SeekDir::SET)

void	clear (const Type type, const SeekDir dir=SeekDir::SET)

Type	type () const

void	setType (const Type type)

SeekDir	whence () const

void	setWhence (const SeekDir dir)

off_t	start () const

void	setStart (const off_t start)

off_t	length () const

void	setLength (const off_t len)

ProcessID	pid () const

void	clearPID ()
	reset the process ID to zero which is a requirement for setting OFD locks.

bool	isOFDLock () const
	Check output data whether it describes an OFD lock.

Detailed Description

Wrapper around struct flock used for advisory file locking in FileDescriptor.

This type is used together with FileDescriptor::setLock(), FileDescriptor::setOFDLock() and related functions. The flock data structure describes a byte region of a file to be locked. A combination of SeekDir::SET with a length of zero will lock the complete file.

Advisory file locking requires the cooperation of all processes accessing a file, to work. There exist two types of advisory file locking: traditional POSIX compatible locks and Linux specific open file description (OFD) locks. The traditional locks have unfortunate semantics that tie a lock to a single process, not to an open file description. The Linux specific open file description (OFD) locks have better semantics, where a lock is placed on the open file description and multiple file descriptors can refer to it. OFD locks are also planned to be part of future POSIX specifications.

For new programs the OFD style locks should always be used in preference over the traditional locks, except if compatibility with existing software is a requirement. This structure is used for both, traditional and OFD locks. For OFD locks the pid() value must be zero, which is achieved by calling the constructor, clear() or clearPID().

Things to consider:

for placing a READ_LOCK the file must be open for reading, for placing a WRITE_LOCK it must be open for writing and for placing both types of locks it needs to be open for read-write.
traditional locks have basic deadlock detection support in the kernel, but there are some limitations to this. OFD locks currently don't have deadlock detection.
traditional locks are not inherited via fork(), but are preserved across execve(). A close on any file descriptor referring to the lock, will be remove the lock, even if other file descriptors for the open file description exist.
traditional locks always conflict with OFD locks, even if the same process acquires them on the same file descriptor.
OFD locks placed on the same open file description are always compatible with each other and can be used for converting existing locks.
Both traditional and OFD locks allow to convert existing locks already owned by the caller, which may result in splitting or merging of lock regions.
OFD locks can be used to synchronize between threads of the same process if each thread performs an independent open() on the file to lock.

Definition at line 59 of file FileLock.hxx.

Member Enumeration Documentation

◆ SeekDir

enum class cosmos::FileLock::SeekDir : short

strong

Definition at line 72 of file FileLock.hxx.

                           : short {
                SET = SEEK_SET,
                CUR = SEEK_CUR,
                END = SEEK_END
        };

◆ Type

enum class cosmos::FileLock::Type : short

strong

Definition at line 63 of file FileLock.hxx.

                        : short {
                READ_LOCK  = F_RDLCK,
                WRITE_LOCK = F_WRLCK,
                UNLOCK     = F_UNLCK
        };

Constructor & Destructor Documentation

◆ FileLock()

cosmos::FileLock::FileLock	(	const Type	type,
		const SeekDir	dir = SeekDir::SET )

inlineexplicit

Definition at line 80 of file FileLock.hxx.

                                                                           {
                clear(type, dir);
        }

Member Function Documentation

◆ clear()

void cosmos::FileLock::clear	(	const Type	type,
		const SeekDir	dir = SeekDir::SET )

inline

Definition at line 84 of file FileLock.hxx.

                                                                    {
                zero_object(static_cast<flock&>(*this));
                setType(type);
                setWhence(dir);
        }

◆ clearPID()

void cosmos::FileLock::clearPID ( )

inline

reset the process ID to zero which is a requirement for setting OFD locks.

Definition at line 127 of file FileLock.hxx.

                        {
                this->l_pid = 0;
        }

◆ isOFDLock()

bool cosmos::FileLock::isOFDLock ( ) const

inline

Check output data whether it describes an OFD lock.

Data returned from FileDescriptor::getOFDLock() will set an invalid process ID if the lock describes an OFD lock. Otherwise it is a traditional POSIX compatible lock.

Definition at line 137 of file FileLock.hxx.

                               {
                return pid() == ProcessID::INVALID;
        }

◆ length()

off_t cosmos::FileLock::length ( ) const

inline

Definition at line 114 of file FileLock.hxx.

                             {
                return this->l_len;
        }

◆ pid()

ProcessID cosmos::FileLock::pid ( ) const

inline

Definition at line 122 of file FileLock.hxx.

                              {
                return ProcessID{this->l_pid};
        }

◆ setLength()

void cosmos::FileLock::setLength ( const off_t len )

inline

Definition at line 118 of file FileLock.hxx.

                                        {
                this->l_len = len;
        }

◆ setStart()

void cosmos::FileLock::setStart ( const off_t start )

inline

Definition at line 110 of file FileLock.hxx.

                                         {
                this->l_start = start;
        }

◆ setType()

void cosmos::FileLock::setType ( const Type type )

inline

Definition at line 94 of file FileLock.hxx.

                                      {
                this->l_type = cosmos::to_integral(type);
        }

◆ setWhence()

void cosmos::FileLock::setWhence ( const SeekDir dir )

inline

Definition at line 102 of file FileLock.hxx.

                                          {
                this->l_whence = cosmos::to_integral(dir);
        }

◆ start()

off_t cosmos::FileLock::start ( ) const

inline

Definition at line 106 of file FileLock.hxx.

                            {
                return this->l_start;
        }

◆ type()

Type cosmos::FileLock::type ( ) const

inline

Definition at line 90 of file FileLock.hxx.

                          {
                return Type{this->l_type};
        }

◆ whence()

SeekDir cosmos::FileLock::whence ( ) const

inline

Definition at line 98 of file FileLock.hxx.

                               {
                return SeekDir{this->l_whence};
        }

The documentation for this class was generated from the following file:

include/fs/FileLock.hxx

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ SeekDir

◆ Type

Constructor & Destructor Documentation

◆ FileLock()

Member Function Documentation

◆ clear()

◆ clearPID()

◆ isOFDLock()

◆ length()

◆ pid()

◆ setLength()

◆ setStart()

◆ setType()

◆ setWhence()

◆ start()

◆ type()

◆ whence()