pstore::file::range_lock Class Reference

A synchronization object that can be used to protect data in a file from being simultaneously accessed by multiple processes. More...

#include <file.hpp>

Public Member Functions
	range_lock () noexcept=default
	Default constructs an instance of range_lock. More...
	range_lock (file_base *const file, std::uint64_t offset, std::size_t size, file_base::lock_kind kind) noexcept
	range_lock (range_lock const &other)=delete
	range_lock (range_lock &&other) noexcept
	~range_lock () noexcept
	Destroys the range lock. More...
range_lock &	operator= (range_lock &&other) noexcept
	Move assignment operator. More...
range_lock &	operator= (range_lock const &)=delete
bool	lock ()
	Blocks until a lock can be obtained for the current thread. More...
bool	try_lock ()
	Attempts to acquire the lock for the current thread without blocking. More...
void	unlock ()
	Releases the file range lock which should be previously be locked by a call to lock() or try_lock(). More...
Observers
file_base *	file () noexcept
file_base const *	file () const noexcept
std::uint64_t	offset () const noexcept
std::size_t	size () const noexcept
file_base::lock_kind	kind () const noexcept
bool	is_locked () const noexcept

Detailed Description

A synchronization object that can be used to protect data in a file from being simultaneously accessed by multiple processes.

It supports a non-recursive multiple-reader/single writer access model:

• A process owns a range lock from the time that it successfully calls either lock or try_lock until it calls unlock.
• When a process has an exclusive_write lock, all other processes will block (for calls to lock) or receive a false return for try_lock) if they attempt to claim ownership of the range_lock.
• A calling process must not own the range_lock prior to calling lock or try_lock.

The behavior of the program is undefined if a range lock is destroyed while still owned. The range_lock class satisfies all requirements of Lockable and StandardLayoutType; it is not copyable.

Note

range_lock is usually not accessed directly: std::unique_lock and std::lock_guard are used to manage locking in exception-safe manner. The class is a relatively thin wrapper around the file_base::lock() and file_base::unlock() methods.

Constructor & Destructor Documentation

range_lock() [1/2]

pstore::file::range_lock::range_lock ( )

defaultnoexcept

Default constructs an instance of range_lock.

The following values are set:

• file is nullptr
• offset is 0
• size is 0
• kind is file_base::lock_kind::shared_read
• is_locked will return false

range_lock() [2/2]

pstore::file::range_lock::range_lock ( file_base *const  file, std::uint64_t  offset, std::size_t  size, file_base::lock_kind  kind  )

noexcept

Parameters

file	The file whose contents are to be range-locked.
offset	The offset of the first byte of the file to be locked.
size	The number of bytes to be locked.
kind	Specifies the type of lock to be obtained

~range_lock()

pstore::file::range_lock::~range_lock ( )

noexcept

Destroys the range lock.

If the lock is owned, it will be unlocked but an error will be lost.

Member Function Documentation

kind()

file_base::lock_kind pstore::file::range_lock::kind ( ) const

inlinenoexcept

Returns

The type of lock to be obtained when lock() is called.

lock()

bool pstore::file::range_lock::lock

(

)

Blocks until a lock can be obtained for the current thread.

If an exception is thrown, no lock is obtained.

Returns

False if the lock was already owned before the call or no file is associated with this object otherwise true.

offset()

std::uint64_t pstore::file::range_lock::offset ( ) const

inlinenoexcept

Returns

The offset of the first locked byte of the file to be locked.

operator=()

range_lock & pstore::file::range_lock::operator= ( range_lock &&  other )

noexcept

Move assignment operator.

Replaces the contents with those of "other" using move semantics. If prior to the call *this has an associated mutex and has acquired ownership of it, the mutex is unlocked. If this operation fails, the resulting exception is dropped.

size()

std::size_t pstore::file::range_lock::size ( ) const

inlinenoexcept

Returns

The number bytes to be locked.

try_lock()

bool pstore::file::range_lock::try_lock

(

)

Attempts to acquire the lock for the current thread without blocking.

If an exception is thrown, no lock is obtained.

Returns

true if the lock was acquired, false otherwise.

unlock()

void pstore::file::range_lock::unlock

(

)

Releases the file range lock which should be previously be locked by a call to lock() or try_lock().

---

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

• include/pstore/os/file.hpp
• lib/os/file.cpp