TITLE:: FluidBufThreadDemo
SUMMARY:: A Tutorial Object to Experiment with Multithreading in FluidBuf* Objects
CATEGORIES:: Libraries>FluidCorpusManipulation
RELATED::  Guides/FluidCorpusManipulation, 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/FluidCorpusManipulation##Fluid Corpus Manipulation Toolkit::. 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, processBlocking
	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:: freeWhenDone
Free the server instance when processing complete. Default true

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:: trig
	The trigger to start the job.

ARGUMENT:: blocking
    The thread on which the job is processed.

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, action:{|x|x.get(0,{|y|y.postln});});

// as the 'process' returns its instance, we can cancel the process easily
c = FluidBufThreadDemo.process(s, b, 100000, action: {|x|x.get(0,{|y|y.postln});});
c.cancel;

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