apprentice/README.md

# Apprentice #
   A task based thread scheduling library. It will track and maintain
compute and blocking threads. The scheduler will then handle issuing tasks
amoung the threads it maintains.

## Threads ##
   Threads are implemented using the Rust standard library threads. These will
be managed by a scheduler. Each scheduler has two types of threads that it
distinguishes against. Blocking and Compute.

### Blocking ###
   Blocking threads are threads with tasks that will block while they are
being processed. Tasks that do not block can be run here as well if you need
to spawn more threads than the scheduler keeps alive for compute threads.
However, non blocking tasks would be better run on a compute thread.

### Compute ###
   Compute threads are threads with tasks that will never block. This is
a strict requirement that the programmer must adhere to. Compute threads and
task sharing will not work if all the available compute threads are blocked.

## Tasks ##
   Tasks are the thread safe portions of code that you wish to write. These
can be blocking or non blocking. If a task is marked as Immortal, then like
the pheonix, when it is finished processing the reset function will be called
and the task will be set to run again. By default, however, tasks are Mortal
and will not be reset and reprocessed.

## Scheduler ##
   The scheduler creates and maintains all the compute and blocking threads
it needs to run and processs tasks given to it. The scheduler will destroy
threads that it determines are not needed. You can create multiple schedulers
and each one will maintain its own set of threads and tasks. A single, program
wide scheduler, can be created and accessed by libraries that need to spawn
tasks as well. It is recommended to use this as your main scheduler and it
can be set and retieved by your program.