Nanothread Programmers Guide - Draft
		------------------------------------



In the context of the Nanothreads environment, an application achieves
parallelism by having a number of physical processors, or simply
processors, assigned to it.  A Virtual Processor (VP) is a software
abstraction of the processor.  Initially, an application requests a
number of processors. A further request results in an equal number of
VPs being created.

	o The number of processors is requested with
	  set_num_processors(n), where n is the number of processors
	  being requested. Set_num_processors also sets up the arena
	  for kernel-user communication, which can be accessed through
	  the variable "kusp".

	o VPs are assigned to the application when start_threads(startf, arg)
	  is called.  Each allocated VP starts running the function startf(arg).

	o Each VP is assigned an ID, which is a small integer.
	  The function getvpid() returns the id of the current VP.

The kernel records changes to the state of the VPs in the kernel-user
communication arena.  The field 'nallocated' in kusp is the number of
VPs which are bound to a physical processor, that is, the number of VPs
dispatched, and running on a processor.  The field 'rbits' in kusp
indicates whether a VP has had its underlying processor preempted, such
that for VP with ID "i":

	o btst(kusp->rbits,i) = 1, iff VP(i) is preempted.

If a VP(i) finds that it has no work to do, and finds another VP(j) not
bound to any physical processor using the above test, then it can give
up its processor with the resume_vp() call: resume_vp(j) results in
VP(j) being bound to the physical processor on which the call was
executed.


Other than the operating system preempting a VP, an application can
control the state of its VPs with block_vp() and unblock_vp():

	o block_vp(i) ensures that a VP(i) is not bound to a physical
	  processor until a corresponding unblock_vp(i) is called.



Current Implementation Notes:
----------------------------

	o VPs are sprocs.
	o set_num_processors can be called only once.
	o currently, resume_vp(j) just gives up the physical processor 
	  corresponding to the VP making the call: it does not
	  necessarily pickup VP(j) to be bound to that processor.