document Lock

lib/Type/Lock.pod

@@ -0,0 +1,59 @@
+=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;         #
+
+High-level Perl 6 code should awoid 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
+
+    method protect(Lock:D: &code)
+
+Runs C<&code> and makes sure it is only run in one thread at once.
+
+=head2 method lock
+
+    method lock(Lock:D:)
+
+Acquires the lock. If it is currently not available, waits for it.
+
+=head2 method unlock
+
+    method lock(Lock:D:)
+
+Releases the lock.
+
+=head2 method condition
+
+    my class ConditionVariable {
+        method wait();
+        method signal();
+        method signal_all();
+    }
+
+    method condition(Lock:D:) returns ConditionVariable:D
+
+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