=begin pod

=TITLE class Lock

=SUBTITLE Low-level thread locking primitive

    class Lock { ... }

A Lock is a low-level constructor for ensuring that only one thread works with
a certain object at a given time, or runs a piece of code (called the
I<critical section>).

    my $x = 0;
    my $l = Lock.new;
    await for (^10).map: {
        $l.protect({ $x++ });
    }
    say $x;         #

Locks are reentrant, that is, a thread that holds the lock can lock it again
without blocking.

High-level Perl 6 code should avoid the direct usage of locks, because they
are not composable. Instead, high-level constructs such as
L<Promise|/type/Promise>, L<Channel|/type/Channel> and Supply should be used
whenever possible.

=head1 Methods

=head2 method protect

Defined as:

    method protect(Lock:D: &code)

Usage:

    LOCK.protect(CODE)

Runs C<&code> and makes sure it is only run in one thread at once.

=head2 method lock

Defined as:

    method lock(Lock:D:)

Usage:

    LOCK.lock

Acquires the lock. If it is currently not available, waits for it.

=head2 method unlock

Defined as:

    method unlock(Lock:D:)

Usage:

    LOCK.unlock

Releases the lock.

=head2 method condition

Defined as:

    my class ConditionVariable {
        method wait();
        method signal();
        method signal_all();
    }

    method condition(Lock:D:) returns ConditionVariable:D

Usage:

    LOCK.condition

Returns a condition variable. Compare
L<http://web.stanford.edu/class/cs140/cgi-bin/lecture.php?topic=locks> or
L<http://en.wikipedia.org/wiki/Monitor_%28synchronization%29> for background.

=end pod
