The monitor concurrency control interface. Class READ_WRITE_MONITOR implements the monitor concurrency control paradigm, as described in Andrews, "Concurrent Programming Principles and Practice". We have extended Andrews design to incorporate two kinds of clients: threads and objects. The thread client interface corresponds to Andrew's design and is intended to mediate access by multiple clients, each of which is expected to gain appropriate access, execute some piece of code and release access. The object client interface is intended for use when a client object depends on the monitored object not changing during the lifetime of the client object. The client gains read-only access to the monitored object and releases the access only when it (the client) is deleted. The read access prevents any thread from gaining write access and hence locks the monitored object for the life of the client. The motivating application for the object client interface is the need to lock poset objects which are being used as the schema for some other (client) poset object.

Note that the monitor protocol for the per-thread access control only works if three conditions are satisfied:

request_precedes_access:
every client always requests access before accessing the object

request_precedes_release:
every release call by this thread is always preceded by a request call by this thread

release_follows_request:
every request call by this thread is always followed by a release call by this thread

The latter two conditions require that request/release always occur in matching pairs.

We are currently enforcing request_precedes_access and request_precedes_release via precondition assertions but we are not enforcing release_follows_request because we don't see any way to do it.

We sometimes refer to a client that satisfies request_precedes_access as a "polite" client, and a client that satisfies request_precedes_release and release_follows_request as a "proper" client. The read_write_monitor protocol implemented here requires clients to be both polite and proper.
A note on constness. "Logically" const member functions (queries) of monitored classes must be able to get and release read access. This implies that get_read_access and release_access must be const; which in turn requires that in this class most of the other member functions are const and all the data members are mutable. More...

#include <read_write_monitor.h>

Inheritance diagram for sheaf::read_write_monitor:

Friends
class	read_write_monitor_handle

READ_WRITE_MONITOR FACET
	read_write_monitor ()
	Default Constructor. More...

virtual	~read_write_monitor ()
	Destructor. More...

GLOBAL ACCESS CONTROL FACET
static bool	access_control_disabled ()
	True if access control mechanism is disabled. Default value is enabled (false) and access is controlled by the per-thread access control functions. Disabled (true) is equivalent to having read-write access at all times, irrespective of any access control requests. More...

static void	enable_access_control ()
	Enables access control. Should only be invoked once at beginning of a program, before any other SheafSystem calls. Once enabled, access control can not be disabled. More...

PER-THREAD ACCESS CONTROL FACET
bool	is_read_accessible () const
	True if this thread has read-only or read-write access. More...

bool	is_not_read_accessible () const
	True if this thread has neither read-only or read-write access or if access control is disabled. More...

bool	is_read_write_accessible () const
	True if this thread has read-write access or if access control is not enabled. More...

bool	is_not_read_write_accessible () const
	True if this thread does not have read-write access or if access control is not enabled. More...

bool	is_read_only_accessible () const
	True if this thread has read-only access. More...

bool	is_not_read_only_accessible () const
	True if this thread does not have read-only access. More...

int	access_request_depth () const
	Number of times access has been granted without a corresponding release. More...

void	get_read_access () const
	Get read access to the state associated with this. More...

void	get_read_write_access (bool xrelease_read_only_access=false)
	Get read write access to the state associated with this. If release_read_only_access is requested, read only access will be released then read_write_access will be requested, finally the same level of read_access as before will be requested. More...

void	release_access (bool xall=false) const
	Release access. If xall is true, release all levels of access. Otherwise, release one level of access. More...

bool	access_guards_disabled () const
	True if access guards disabled. More...

void	disable_access_guards ()
	Disables access gaurds; intended for use only within constructors of monitored objects, where no other client can possibly have access (yet). More...

void	enable_access_guards ()
	Re-enables access guards. More...

NOTIFICATION FACET
bool	is_modified () const
	True if any client has had read-write access to this object since the last call to clear_is_modified();. More...

void	clear_is_modified ()
	Makes is_modified() false. More...

MODE LOCK CONTROL FACET
bool	is_mode_locked () const

int	mode_lock_ct () const

void	get_mode_lock ()

void	release_mode_lock ()

ANY FACET
virtual bool	is_ancestor_of (const any *xother) const
	True if other conforms to current. More...

virtual read_write_monitor *	clone () const
	Make a new instance of the same type as this. More...

virtual bool	invariant () const
	Class invariant. More...

Additional Inherited Members
Public Member Functions inherited from sheaf::any
bool	is_same_type (const any *other) const
	True if other is the same type as this. More...

virtual	~any ()
	Destructor. More...

bool	invariant_check () const
	True if invariant checking is enabled. More...

void	enable_invariant_check () const
	Enable invariant checking. More...

void	disable_invariant_check () const
	Disable invariant check. Intended for preventing recursive calls to invariant and for suppressing invariant checking during multi-phase initialization. More...

int	disable_invariance_check_request_depth () const
	Number of times disable_invariant_check has been called without matching call to enable_invariant_check. More...

Protected Member Functions inherited from sheaf::any
	any ()
	default constructor More...

Detailed Description

The monitor concurrency control interface. Class READ_WRITE_MONITOR implements the monitor concurrency control paradigm, as described in Andrews, "Concurrent Programming Principles and Practice". We have extended Andrews design to incorporate two kinds of clients: threads and objects. The thread client interface corresponds to Andrew's design and is intended to mediate access by multiple clients, each of which is expected to gain appropriate access, execute some piece of code and release access. The object client interface is intended for use when a client object depends on the monitored object not changing during the lifetime of the client object. The client gains read-only access to the monitored object and releases the access only when it (the client) is deleted. The read access prevents any thread from gaining write access and hence locks the monitored object for the life of the client. The motivating application for the object client interface is the need to lock poset objects which are being used as the schema for some other (client) poset object.

Note that the monitor protocol for the per-thread access control only works if three conditions are satisfied:

request_precedes_access:
every client always requests access before accessing the object

request_precedes_release:
every release call by this thread is always preceded by a request call by this thread

release_follows_request:
every request call by this thread is always followed by a release call by this thread

The latter two conditions require that request/release always occur in matching pairs.

We are currently enforcing request_precedes_access and request_precedes_release via precondition assertions but we are not enforcing release_follows_request because we don't see any way to do it.

We sometimes refer to a client that satisfies request_precedes_access as a "polite" client, and a client that satisfies request_precedes_release and release_follows_request as a "proper" client. The read_write_monitor protocol implemented here requires clients to be both polite and proper.
A note on constness. "Logically" const member functions (queries) of monitored classes must be able to get and release read access. This implies that get_read_access and release_access must be const; which in turn requires that in this class most of the other member functions are const and all the data members are mutable.

Definition at line 101 of file read_write_monitor.h.

Constructor & Destructor Documentation

◆ read_write_monitor()

sheaf::read_write_monitor::read_write_monitor ( )

Default Constructor.

Postcondition

invariant()

Definition at line 33 of file read_write_monitor.cc.

References disable_access_guards(), sheaf::any::disable_invariant_check(), enable_access_guards(), sheaf::any::enable_invariant_check(), invariant(), and ~read_write_monitor().

Referenced by clone().

◆ ~read_write_monitor()

sheaf::read_write_monitor::~read_write_monitor ( )

virtual

Destructor.

Definition at line 94 of file read_write_monitor.cc.

References access_control_disabled().

Referenced by read_write_monitor().

Member Function Documentation

◆ access_control_disabled()

bool sheaf::read_write_monitor::access_control_disabled ( )

static

True if access control mechanism is disabled. Default value is enabled (false) and access is controlled by the per-thread access control functions. Disabled (true) is equivalent to having read-write access at all times, irrespective of any access control requests.

Definition at line 121 of file read_write_monitor.cc.

References enable_access_control().

Referenced by sheaf::read_write_monitor_handle::access_control_disabled(), fields::field_vd::access_control_disabled(), enable_access_control(), is_not_read_accessible(), is_not_read_write_accessible(), is_read_only_accessible(), is_read_write_accessible(), and ~read_write_monitor().

◆ access_guards_disabled()

bool sheaf::read_write_monitor::access_guards_disabled ( ) const

protected

True if access guards disabled.

Definition at line 538 of file read_write_monitor.cc.

References disable_access_guards().

Referenced by is_mode_locked(), is_read_only_accessible(), is_read_write_accessible(), and release_access().

◆ access_request_depth()

int sheaf::read_write_monitor::access_request_depth ( ) const

Number of times access has been granted without a corresponding release.

Definition at line 342 of file read_write_monitor.cc.

References get_read_access().

Referenced by sheaf::read_write_monitor_handle::access_request_depth(), sheaf::read_write_monitor_handle::get_read_access(), sheaf::read_write_monitor_handle::get_read_write_access(), get_read_write_access(), is_not_read_only_accessible(), sheaf::read_write_monitor_handle::release_access(), and release_access().

◆ clear_is_modified()

void sheaf::read_write_monitor::clear_is_modified ( )

Makes is_modified() false.

Definition at line 1146 of file read_write_monitor.cc.

References is_mode_locked().

Referenced by sheaf::read_write_monitor_handle::clear_state_is_modified(), and is_modified().

◆ clone()

sheaf::read_write_monitor * sheaf::read_write_monitor::clone ( ) const

virtual

Make a new instance of the same type as this.

Postcondition

result != 0

Reimplemented from sheaf::any.

Reimplemented in sheaf::poset_state.

Definition at line 1375 of file read_write_monitor.cc.

References invariant(), and read_write_monitor().

Referenced by is_ancestor_of().

◆ disable_access_guards()

void sheaf::read_write_monitor::disable_access_guards ( )

protected

Disables access gaurds; intended for use only within constructors of monitored objects, where no other client can possibly have access (yet).

Definition at line 547 of file read_write_monitor.cc.

References enable_access_guards().

Referenced by access_guards_disabled(), and read_write_monitor().

◆ enable_access_control()

void sheaf::read_write_monitor::enable_access_control ( )

static

Enables access control. Should only be invoked once at beginning of a program, before any other SheafSystem calls. Once enabled, access control can not be disabled.

Postcondition

!access_control_disabled()

Definition at line 150 of file read_write_monitor.cc.

References access_control_disabled(), and is_read_accessible().

Referenced by access_control_disabled(), sheaf::read_write_monitor_handle::enable_access_control(), and fields::field_vd::enable_access_control().

◆ enable_access_guards()

void sheaf::read_write_monitor::enable_access_guards ( )

protected

Re-enables access guards.

Definition at line 556 of file read_write_monitor.cc.

References invariant(), and is_modified().

Referenced by disable_access_guards(), and read_write_monitor().

◆ get_mode_lock()

void sheaf::read_write_monitor::get_mode_lock ( )

Deprecated:: No replacement. "mode" is a submode of write access. The mode lock can be used by an application to prohibit access to some features even to a client that has write access. For instance, in class poset_state_handle, jim edit mode is disabled when is_mode_locked is true.

Precondition

access_mode() != 0

Postcondition

invariant()

_mode_lock_ct == old_mode_lock_ct + 1

_mode_lock_ct > 0

Definition at line 1232 of file read_write_monitor.cc.

References invariant(), and release_mode_lock().

Referenced by sheaf::read_write_monitor_handle::get_mode_lock(), and mode_lock_ct().

◆ get_read_access()

void sheaf::read_write_monitor::get_read_access ( ) const

Get read access to the state associated with this.

Postcondition

is_read_accessible()

Definition at line 369 of file read_write_monitor.cc.

References get_read_write_access(), and is_read_accessible().

Referenced by access_request_depth(), and sheaf::read_write_monitor_handle::get_read_access().

◆ get_read_write_access()

void sheaf::read_write_monitor::get_read_write_access ( bool xrelease_read_only_access = false )

Get read write access to the state associated with this. If release_read_only_access is requested, read only access will be released then read_write_access will be requested, finally the same level of read_access as before will be requested.

Precondition

xrelease_read_only_access || !is_read_only_accessible()

Postcondition

is_read_write_accessible()

access_request_depth() == old_access_request_depth + 1

Definition at line 407 of file read_write_monitor.cc.

References access_request_depth(), is_read_only_accessible(), is_read_write_accessible(), and release_access().

Referenced by get_read_access(), and sheaf::read_write_monitor_handle::get_read_write_access().

◆ invariant()

bool sheaf::read_write_monitor::invariant ( ) const

virtual

Class invariant.

Reimplemented from sheaf::any.

Reimplemented in sheaf::poset_state.

Definition at line 1396 of file read_write_monitor.cc.

References sheaf::any::disable_invariant_check(), sheaf::any::enable_invariant_check(), and sheaf::any::invariant_check().

Referenced by clone(), enable_access_guards(), get_mode_lock(), sheaf::poset_state::invariant(), read_write_monitor(), and release_mode_lock().

◆ is_ancestor_of()

bool sheaf::read_write_monitor::is_ancestor_of ( const any * xother ) const

virtual

True if other conforms to current.

Reimplemented from sheaf::any.

Reimplemented in sheaf::poset_state.

Definition at line 1355 of file read_write_monitor.cc.

References clone().

Referenced by release_mode_lock().

◆ is_mode_locked()

bool sheaf::read_write_monitor::is_mode_locked ( ) const

Deprecated:: No replacement. "mode" is a submode of write access. The mode lock can be used by an application to prohibit access to some features even to a client that has write access. For instance, in class poset_state_handle, jim edit mode is disabled when is_mode_locked is true.

Definition at line 1176 of file read_write_monitor.cc.

References access_guards_disabled(), and mode_lock_ct().

Referenced by clear_is_modified(), and sheaf::read_write_monitor_handle::state_is_mode_locked().

◆ is_modified()

bool sheaf::read_write_monitor::is_modified ( ) const

True if any client has had read-write access to this object since the last call to clear_is_modified();.

Definition at line 1118 of file read_write_monitor.cc.

References clear_is_modified().

Referenced by enable_access_guards(), and sheaf::read_write_monitor_handle::state_is_modified().

◆ is_not_read_accessible()

bool sheaf::read_write_monitor::is_not_read_accessible ( ) const

True if this thread has neither read-only or read-write access or if access control is disabled.

Postcondition

result == (access_control_disabled() || !is_read_accessible())

Definition at line 226 of file read_write_monitor.cc.

References access_control_disabled(), is_read_accessible(), and is_read_write_accessible().

Referenced by is_read_accessible(), release_access(), and sheaf::read_write_monitor_handle::state_is_not_read_accessible().

◆ is_not_read_only_accessible()

bool sheaf::read_write_monitor::is_not_read_only_accessible ( ) const

True if this thread does not have read-only access.

Postcondition

result == !is_read_only_accessible()

Definition at line 313 of file read_write_monitor.cc.

References access_request_depth(), and is_read_only_accessible().

Referenced by is_read_only_accessible(), and sheaf::read_write_monitor_handle::state_is_not_read_only_accessible().

◆ is_not_read_write_accessible()

bool sheaf::read_write_monitor::is_not_read_write_accessible ( ) const

True if this thread does not have read-write access or if access control is not enabled.

Postcondition

result == (access_control_disabled() ? true: !is_read_write_accessible())

Definition at line 269 of file read_write_monitor.cc.

References access_control_disabled(), is_read_only_accessible(), and is_read_write_accessible().

Referenced by is_read_write_accessible(), and sheaf::read_write_monitor_handle::state_is_not_read_write_accessible().

◆ is_read_accessible()

bool sheaf::read_write_monitor::is_read_accessible ( ) const

True if this thread has read-only or read-write access.

Postcondition

result == (is_read_only_accessible() || is_read_write_accessible())

Definition at line 205 of file read_write_monitor.cc.

References is_not_read_accessible(), is_read_only_accessible(), and is_read_write_accessible().

Referenced by enable_access_control(), get_read_access(), is_not_read_accessible(), release_access(), and sheaf::read_write_monitor_handle::state_is_read_accessible().

◆ is_read_only_accessible()

bool sheaf::read_write_monitor::is_read_only_accessible ( ) const

True if this thread has read-only access.

Postcondition

(access_control_disabled() || access_guards_disabled()) ? !result : true

Definition at line 288 of file read_write_monitor.cc.

References access_control_disabled(), access_guards_disabled(), and is_not_read_only_accessible().

Referenced by get_read_write_access(), is_not_read_only_accessible(), is_not_read_write_accessible(), is_read_accessible(), and sheaf::read_write_monitor_handle::state_is_read_only_accessible().

◆ is_read_write_accessible()

bool sheaf::read_write_monitor::is_read_write_accessible ( ) const

True if this thread has read-write access or if access control is not enabled.

Postcondition

(access_control_disabled() || access_guards_disabled()) ? result : true

Definition at line 247 of file read_write_monitor.cc.

References access_control_disabled(), access_guards_disabled(), and is_not_read_write_accessible().

Referenced by get_read_write_access(), is_not_read_accessible(), is_not_read_write_accessible(), is_read_accessible(), and sheaf::read_write_monitor_handle::state_is_read_write_accessible().

◆ mode_lock_ct()

int sheaf::read_write_monitor::mode_lock_ct ( ) const

Deprecated:: No replacement. "mode" is a submode of write access. The mode lock can be used by an application to prohibit access to some features even to a client that has write access. For instance, in class poset_state_handle, jim edit mode is disabled when is_mode_locked is true.

Definition at line 1204 of file read_write_monitor.cc.

References get_mode_lock().

Referenced by is_mode_locked(), and sheaf::read_write_monitor_handle::mode_lock_ct().

◆ release_access()

void sheaf::read_write_monitor::release_access ( bool xall = false ) const

Release access. If xall is true, release all levels of access. Otherwise, release one level of access.

Precondition

is_read_accessible()

Postcondition

xall ? is_not_read_accessible() : true

Definition at line 463 of file read_write_monitor.cc.

References access_guards_disabled(), access_request_depth(), is_not_read_accessible(), and is_read_accessible().

Referenced by get_read_write_access(), and sheaf::read_write_monitor_handle::release_access().

◆ release_mode_lock()

void sheaf::read_write_monitor::release_mode_lock ( )

Deprecated:: No replacement. "mode" is a submode of write access. The mode lock can be used by an application to prohibit access to some features even to a client that has write access. For instance, in class poset_state_handle, jim edit mode is disabled when is_mode_locked is true.

Precondition

_mode_lock_ct > 0

Postcondition

invariant()

_mode_lock_ct == old_mode_lock_ct - 1

Definition at line 1291 of file read_write_monitor.cc.

References invariant(), and is_ancestor_of().

Referenced by get_mode_lock(), and sheaf::read_write_monitor_handle::release_mode_lock().

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

Friends

READ_WRITE_MONITOR FACET

GLOBAL ACCESS CONTROL FACET

PER-THREAD ACCESS CONTROL FACET

NOTIFICATION FACET

MODE LOCK CONTROL FACET

ANY FACET

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ read_write_monitor()

◆ ~read_write_monitor()

Member Function Documentation

◆ access_control_disabled()

◆ access_guards_disabled()

◆ access_request_depth()

◆ clear_is_modified()

◆ clone()

◆ disable_access_guards()

◆ enable_access_control()

◆ enable_access_guards()

◆ get_mode_lock()

◆ get_read_access()

◆ get_read_write_access()

◆ invariant()

◆ is_ancestor_of()

◆ is_mode_locked()

◆ is_modified()

◆ is_not_read_accessible()

◆ is_not_read_only_accessible()

◆ is_not_read_write_accessible()

◆ is_read_accessible()

◆ is_read_only_accessible()

◆ is_read_write_accessible()

◆ mode_lock_ct()

◆ release_access()

◆ release_mode_lock()