TITLE:: FluidBufThreadDemo
SUMMARY:: A Tutorial Object to Experiment with Multithreading in FluidBuf* Objects
CATEGORIES:: Libraries>FluidDecomposition
RELATED:: Guides/FluCoMa, Guides/FluidDecomposition, Guides/FluidBufMultiThreading

DESCRIPTION::
This class implements a simple tutorial object to illustrate and experiment with the behaviour of the FluidBuf* objects.  It is part of the LINK:: Guides/FluidDecomposition:: of LINK:: Guides/FluCoMa::. For more explanations, learning material, and discussions on its musicianly uses, visit http://www.flucoma.org/

It simply starts a process that will, upon completion of its task, write a single value to the destination buffer. This is the general behaviour of much of the CPU consuming FluidBuf* objects. In this case, as a toy example, the task is simply just wait and do nothing, to simulate a task that would actually take that long in the background.

The process will, after waiting for STRONG::time:: millisecond, return its delay lenght as a Float writen at index [0] of the specified destination buffer.

CLASSMETHODS::

METHOD:: process
	This is the method that calls for the job to be done. In this case, simply waiting STRONG::time:: millisecond before writing a value in the destination buffer.

ARGUMENT:: server
	The server on which the destination buffer is declared.

ARGUMENT:: result
	The destination buffer, where the value should be written at the end of the process.

ARGUMENT:: time
	The duration in milliseconds of the delay that the background thread will wait for before yielding the value to the destination buffer.

ARGUMENT:: action
	A function that will be executed upon completion. It is passed the destination buffer as argument.

RETURNS::
	The instance of FluidNRTProcess which can be used to cancel the job.


METHOD:: kr
	This is the UGen that is holding the link with the background thread. It is called by the 'process' method and can be used directly to monitor the progress of the job. For examples of such usage, please refer to the tutorial on link::Guides/FluidBufMultiThreading::.

ARGUMENT:: result
	The destination buffer, where the value should be written at the end of the process.

ARGUMENT:: time
	The duration of the delay that the background thread will wait for before yielding the value to the destination buffer.

ARGUMENT:: doneAction
	An integer representing an action to be executed when the process is finished. This can be used to free the enclosing synth, etc. See link::Classes/Done::  for more detail.

RETURNS::
	It report the approximate job progress, from 0 to 1.


EXAMPLES::

For a thorough explanation, please refer to the tutorial on link::Guides/FluidBufMultiThreading::.

CODE::
// define a destination buffer
b=Buffer.alloc(s,1);

// a simple call, where we query the destination buffer upon completion with the action message.
FluidBufThreadDemo.process(s, b, 1000, {|x|x.get(0,{|y|y.postln});});

// as the 'process' returns its parent UGen, we can cancel the process easily
c = FluidBufThreadDemo.process(s, b, 100000, {|x|x.get(0,{|y|y.postln});});
c.cancel //it stops silently for now but check the synth count going down by 1.

// if a simple call to the UGen is used, the progress can be monitored. The usual cmd. will cancel the job by freeing the synth.
{c = FluidBufThreadDemo.kr(b,10000, Done.freeSelf); Poll.kr(Impulse.kr(2),c);}.scope;
::
