Clarify usage patterns of Task.run

[darioteixeira]

I realise the library's API and documentation are still a work in progress, but currently it doesn't seem to fully leverage the type system to ensure proper usage. Case in point: function Task.parallel_for (and its siblings) will throw an exception unless invoked within a Task.run context, but nothing about its type suggests this. Suppose that instead the signatures for Task.run and Task.parallel_for were something along these lines, where context is an abstract type (actually internally the same as pool):

val run : pool -> (context -> 'a) -> 'a
val parallel_for : ?chunk_size:int -> start:int -> finish:int -> body:(int -> unit) -> context -> unit

This way it would be impossible to invoke Task.parallel_for outside a Task.run context.

Similarly, the current API and documentation is ambiguous regarding the intended usage patterns for Task.run: Should it invoked only once at the top-level, thus making its usage off-limits for libraries, for example?

[kayceesrk]

The proposed solution won't work. You may store the context in a global ref and use it in a context without a Task.run in scope.

We shall aim to clarify the documentation.