4.20. Thread::AutoReadLock Class

Note: This class is not available with the PO_NO_THREAD_CLASSES parse option.

AutoReadLock objects, when used along with a RWLock object, allow Qore programmers to safely acquire and release a read lock, even if exceptions are thrown or return statements are executed in the block where the AutoReadLock object is created. AutoReadLock objects are helper objects that acquire a read lock for the lifetime of the AutoReadLock object. For this reason, it is only appropriate to assign an AutoReadLock object to a local variable, so when the local variable goes out of scope, the AutoReadLock object will be deleted and the read lock will be automatically released.

For example:

our $rwl = new RWLock();

sub check_error($error)
{
    # note that the read lock is acquired in the AutoReadLock constructor, and
    # the read lock will be released as soon as the block is exited below.
    # (with either the throw statement or the return statement)
    my $arl = new AutoReadLock($rwl);
    if ($error)
        throw "ERROR", "sorry, an error happened";

    return "OK";
}

Table 4.857. AutoReadLock Method Overview

Method

Except?

Description

AutoReadLock::constructor()

Y

Creates the AutoReadLock object based on the RWLock argument passed and immediately calls RWLock::readLock().

AutoReadLock::destructor()

Y

Calls RWLock::readUnlock() on the saved RWLock and destroys the AutoReadLock object.

AutoReadLock::copy()

Y

Throws an exception; objects of this class cannot be copied.


4.20.1. AutoReadLock::constructor()

Synopsis

Creates the AutoReadLock object based on the RWLock argument passed. The AutoReadLock object immediately calls RWLock::readLock() on the RWLock object passed, and saves it so it can be released when the AutoReadLock object is destroyed.

Usage
new AutoReadLock(rwlock_object)
Example
my $arl = new AutoReadLock($rwlock);

Table 4.858. Arguments for AutoReadLock::constructor()

Argument

Type

Description

$rwlock

RWLock

The RWLock object to manage for the lifetime of this object.


Table 4.859. Return Values for AutoReadLock::constructor()

Return Type

Description

AutoReadLock Object

The new AutoReadLock object.


4.20.2. AutoReadLock::destructor()

Synopsis

Calls RWLock::readUnlock() on the saved RWLock and destroys the AutoReadLock object.

Usage
delete lvalue
Example
delete $arl;

4.20.3. AutoReadLock::copy()

Synopsis

Throws an exception; objects of this class cannot be copied.

Table 4.860. Arguments for AutoReadLock::copy()

Argument

Type

Description

n/a

n/a

This method takes no arguments.


Table 4.861. Return Values for AutoReadLock::copy()

Return Type

Description

n/a

This method returns no value because it throws an exception.


Table 4.862. Exceptions Thrown by AutoReadLock::copy()

err

desc

AUTOREADLOCK-COPY-ERROR

Objects of this class cannot be copied.