[io grant] Document IO::Handle.lock/.unlock

Rakudo impl: rakudo/rakudo@214198bfb2
Tests: Raku/roast@4194755c19

Author: zoffixznet

doc/Type/IO/Handle.pod6

@@ -64,6 +64,49 @@ for $data-file.lines -> $line {
     @data.push($line.split(','))
 }
 
+=head2 method lock
+
+    method lock(IO::Handle:D:
+        Bool:D :$non-blocking = False, Bool:D :$shared = False --> True
+    )
+
+Places an advisory lock on the filehandle. If C<:$non-blocking> is C<True>
+will L«C<fail>|/routine/fail» with C<X::IO::Lock> if lock could not be
+obtained, otherwise will block until the lock can be placed. If C<:$shared>
+is C<True> will place a shared (read) lock, otherwise will place an
+exclusive (read) lock. On success, returns C<True>; L«fails|/routine/fail»
+with C<X::IO::Lock> if lock cannot be placed (e.g. when trying to place
+a shared lock on a filehandle opened in write mode or trying to
+place an exclusive lock on a filehandle opened in read mode).
+
+You can use C<lock> again to replace an existing lock with another one.
+Use L«C<close>|/routine/close» the filehandle or use
+L«C<unlock>|/routine/unlock» to remove a lock.
+
+=for code :skip-test
+# One program writes, the other reads, and thanks to locks either
+# will wait for the other to finish before proceeding to read/write
+
+# Writer
+with "foo".IO.open(:w) {
+    .lock;
+    .spurt: "I ♥ Perl 6!";
+    .close;
+}
+
+# Reader
+with "foo".IO.open {
+    .lock: :shared;
+    .slurp.say; # OUTPUT: «I ♥ Perl 6!␤»
+    .close;
+}
+
+=head2 method unlock
+
+    method unlock(IO::Handle:D: --> True)
+
+Removes a L«C<lock>|/routine/lock» from the filehandle.
+
 =head2 method words
 
     method words($count = Inf)