start on Promises

Author: jonathanstowe

lib/Language/concurrency.pod

@@ -131,9 +131,33 @@ schedule code to be run straight away on the current thread. The implication
 is that C<cue> on this scheduler will block until the code finishes
 execution, limiting its utility to certain special cases such as testing.
 
-=begin comment
+=head2 Promises
+
+A L<Promise> can be thought of as encapsulating the result of the execution
+of some code that may not have completed or even started at the time the
+promise is obtained.  They provide much of the functionality that user code
+will need to operate in a concurrent or asynchronous manner.
+
+At simplest promises can be thought of as a mechanism for asynchronously
+chaining the results of various callable code:
+
+     my $promise1 = Promise.new();
+     my $promise2 = $promise1.then(-> $v { say $v.result; "Second Result"});
+     $promise1.keep("First Result");
+     say $promise2.result;
 
-=head2 promises
+Here the C<then> schedules code to be executed when the first L<Promise>
+is kept or broken, itself returning a new L<Promise> which will be kept
+with the result of the code when it is executed (or broken if the code
+fails.)  C<keep> changes the status of the promise to C<Kept> setting
+the result to the positional argument. C<result> blocks the current
+thread of execution until the promise is kept or broken, if it was kept
+then it will return the result (that is the value passed to C<keep>, )
+or it will throw an exception based on the value passed to C<break>.
+
+
+
+=begin comment
 
 =head3 start