From ef701d155160d819fb7e979243cae2bd1a88afa6 Mon Sep 17 00:00:00 2001 From: Pierre Alexandre Tremblay Date: Tue, 10 Sep 2019 10:00:26 +0100 Subject: [PATCH] corrected FluidBBufThreadDemo class def, and first draft of help and tutorial --- .../Classes/FluidBufThreadDemo.sc | 4 +- .../Classes/FluidBufThreadDemo.schelp | 74 +++++++++++++++++++ .../Guides/FluidBufMultiThreading.schelp | 31 ++++++++ .../Guides/FluidDecomposition.schelp | 6 +- 4 files changed, 112 insertions(+), 3 deletions(-) create mode 100644 release-packaging/HelpSource/Classes/FluidBufThreadDemo.schelp create mode 100644 release-packaging/HelpSource/Guides/FluidBufMultiThreading.schelp diff --git a/release-packaging/Classes/FluidBufThreadDemo.sc b/release-packaging/Classes/FluidBufThreadDemo.sc index e00432c..bbf9f61 100644 --- a/release-packaging/Classes/FluidBufThreadDemo.sc +++ b/release-packaging/Classes/FluidBufThreadDemo.sc @@ -1,7 +1,7 @@ FluidBufThreadDemo : UGen{ var <>synth, <>server; - *kr {|source, result, time, doneAction = 0| + *kr {|result, time, doneAction = 0| result = result.asUGenInput; @@ -12,7 +12,7 @@ FluidBufThreadDemo : UGen{ ^this.multiNew(\control, result, time, doneAction); } - *process { |server, result, time, action| + *process { |server, result, time = 1000, action| var synth,instance; diff --git a/release-packaging/HelpSource/Classes/FluidBufThreadDemo.schelp b/release-packaging/HelpSource/Classes/FluidBufThreadDemo.schelp new file mode 100644 index 0000000..fd9ee2f --- /dev/null +++ b/release-packaging/HelpSource/Classes/FluidBufThreadDemo.schelp @@ -0,0 +1,74 @@ +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 simply starts a process that will return a single value after a delay, during which it will just wait and do nothing. It is part of the Fluid Decomposition Toolkit of the FluCoMa project.footnote::This was made possible thanks to the FluCoMa project ( http://www.flucoma.org/ ) funded by the European Research Council ( https://erc.europa.eu/ ) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 725899).:: + +The process will return its delay lenght as the first index of the specified destination buffer. + +CLASSMETHODS:: + +METHOD:: process + This is the method that calls for the delay to be . + +ARGUMENT:: server +(describe argument here) + +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:: + Nothing, as the destination buffer is specified in the call. + + +METHOD:: kr + This is the UGEN that is holding the link with the background thread. It is called by the 'process' method. + +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. + + +INSTANCEMETHODS:: + +METHOD:: cancel + This allows to cancel the process on the background thread safely. + +RETURNS:: + Nothing. + + +EXAMPLES:: + +For a thorough explanation, please refer to the tutorial on link::Guides/FluidBufMultiThreading::. + +CODE:: +// define a destination buffer +b=Buffer.alloc(s,1); + +// 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});}); + +// a simple call to the UGEN, where we can monitor the progress and interrup the process without killing the synth +{c = FluidBufThreadDemo.kr(b,10000, Done.freeSelf);}.scope; + +// cancel the job +c.cancel +c.free +:: \ No newline at end of file diff --git a/release-packaging/HelpSource/Guides/FluidBufMultiThreading.schelp b/release-packaging/HelpSource/Guides/FluidBufMultiThreading.schelp new file mode 100644 index 0000000..d17e149 --- /dev/null +++ b/release-packaging/HelpSource/Guides/FluidBufMultiThreading.schelp @@ -0,0 +1,31 @@ +TITLE:: FluidBuf* Multithreading Behaviour +SUMMARY:: A tutorial on the multithreading behaviour of offline processes of the FluCoMa toolbox for signal decomposition +CATEGORIES:: Libraries>FluidDecomposition +RELATED:: Guides/FluCoMa, Guides/FluidDecomposition + +DESCRIPTION:: +The Fluid Decomposition toolbox provides an open-ended, loosely coupled set of objects to break up and analyse sound in terms of slices (segments in time), layers (superositions in time and frequency) and objects (configurable or discoverable patterns in sound). Almost all objects have audio-rate and buffer-based versions. footnote:: +This toolbox was made possible thanks to the FluCoMa project ( http://www.flucoma.org/ ) funded by the European Research Council ( https://erc.europa.eu/ ) under the European Union’s Horizon 2020 research and innovation programme (grant agreement No 725899).:: + +subsection:: basic usage + + show the process method + + show the process returned variable + +subsection:: kr usage + + show the kr monitoring graphically + + show the interruption + + show the interruption again, but in a still working synth, mapping the KR out to a pitch gliss + + +subsection:: bufnmf example + + just for shits and giggles + +subsection: further reading + + a few tutorials on how fucked up it is, includign the thread sync and NRT thread in SC. \ No newline at end of file diff --git a/release-packaging/HelpSource/Guides/FluidDecomposition.schelp b/release-packaging/HelpSource/Guides/FluidDecomposition.schelp index fdbd03a..e3d5d2a 100644 --- a/release-packaging/HelpSource/Guides/FluidDecomposition.schelp +++ b/release-packaging/HelpSource/Guides/FluidDecomposition.schelp @@ -83,4 +83,8 @@ Statistics of buffers subsection:: Utility LINK:: Classes/FluidBufCompose:: -Copy, slice, stack, mix concatenate. All the things you've wanted to do with buffers... \ No newline at end of file +Copy, slice, stack, mix concatenate. All the things you've wanted to do with buffers... + +LINK:: Classes/FluidBufThreadDemo: + +A tutorial object to experiment with multithreading in FluidBuf* objects \ No newline at end of file