benn/lumiera_
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

ProcDispatcher: decide on requirements and implementation structure (#1049)

Browse source
This commit is contained in:
Fischlurch 2016-12-15 20:48:35 +01:00
parent 7e65dda771
commit 00077d0431
11 changed files with 462 additions and 16 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
src/common/guifacade.cpp
View file

@ -121,7 +121,8 @@ namespace gui {
* However, the Lumiera thread handling wrapper/framework ensures that a new thread actually
* starts to execute (and picks up the arguments), prior to returning from the thread starting
* function. For this reason, it is rather unlikely this race actually happens in practice,
* since opening the GuiNotification interface is done early, while starting the UI-Bus.
* since opening the GuiNotification interface is done early, while starting the UI-Bus.
* @todo ////////////////////////////////////////////////////////TICKET #1048 : use Thread.sync (barrier) to work around this!
*/
void
triggerShutdown () noexcept override

23
src/lib/sync.hpp
View file

@ -29,7 +29,7 @@
** describes a way of dealing with synchronisation known to play well with
** scoping, encapsulation and responsibility for a single purpose.
**
** A class becomes \em lockable by inheriting from lib::Sync with the appropriate
** A class becomes _lockable_ by inheriting from lib::Sync with the appropriate
** parametrisation. This causes any instance to inherit a monitor member (object),
** managing a mutex and (optionally) a condition variable for waiting. The actual
** synchronisation is achieved by placing a guard object as local (stack) variable
@ -38,7 +38,7 @@
** manages the locking and unlocking; optionally it may also be used for waiting
** on a condition.
**
** Please note:
** @note
** - It is important to select a suitable parametrisation of the monitor.
** This is done by specifying one of the defined policy classes.
** - Be sure to pick the recursive mutex implementation when recursive calls
@ -176,7 +176,7 @@ namespace lib {
} while(err == EINTR);
if (err) lumiera_lockerror_set (err, &NOBUG_FLAG(sync), NOBUG_CONTEXT_NOFUNC);
return !err;
return not err;
}
bool
@ -187,7 +187,7 @@ namespace lib {
} while(err == EINTR);
if (err) lumiera_lockerror_set (err, &NOBUG_FLAG(sync), NOBUG_CONTEXT_NOFUNC);
return !err;
return not err;
}
@ -405,7 +405,20 @@ namespace lib {
* The interface for clients to access the functionality is the embedded
* Lock template, which should be instantiated as an automatic variable
* within the scope to be protected.
*
*
* ## Usage
* - for *locking*, just place an instant of the embedded Lock into the local
* scope to be protected. All lock instances within the same object share
* the monitor; thus any time, only one of them gets the mutex all other
* instances block on construction.
* - for *waiting* likewise place an instance of the Lock class (which gets
* you a mutex). Then invoke the wait method on that instance; this suspends
* the current thread and releases the mutex. To awake and check the condition,
* some other thread must invoke the Lock::notify() within the same object.
* The Lock::wait() call returns `true` when the condition was met, and
* `false` if awakened due to timeout. The call might throw in case of
* technical errors. In any case, when returning from the `wait()` call,
* the mutex has been re-acquired.
*/
template<class CONF = NonrecursiveLock_NoWait>
class Sync

85
src/proc/control/command-queue.hpp Normal file
View file

@ -0,0 +1,85 @@
/*
COMMAND-QUEUE.hpp - organise ordering of commands within ProcDispatcher
Copyright (C) Lumiera.org
2016, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/** @file command-queue.hpp
** Implementation building block of ProcDispatcher to organise commands.
** This is the actual implementation of the command queue and additionally
** supports some management tasks pertaining to the queue as a whole.
**
** @todo WIP-WIP as of 12/2016
**
** @see CommandQueue_test
** @see proc-dispatcher.hpp
** @see session-command-service.hpp
** @see DispatcherLoop
** @see Looper
**
*/
#ifndef PROC_CONTROL_COMMAND_QUEUE_H
#define PROC_CONTROL_COMMAND_QUEUE_H
#include "lib/error.hpp" ////////TODO needed?
//#include "common/subsys.hpp"
//#include "lib/depend.hpp"
//#include <memory>
//#include <functional>
namespace proc {
namespace control {
// using lib::Symbol;
// using std::bind;
/**
* @todo Type-comment
*/
class CommandQueue
{
public:
CommandQueue()
{ }
/* == diagnostics == */
// size_t size() const ;
// bool empty() const ;
};
////////////////TODO 12/16 currently just fleshing out the API....
}} // namespace proc::control
#endif /*PROC_CONTROL_COMMAND_QUEUE_H*/

87
src/proc/control/looper.hpp Normal file
View file

@ -0,0 +1,87 @@
/*
LOOPER.hpp - proc dispatcher loop and timing control logic
Copyright (C) Lumiera.org
2016, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/** @file looper.hpp
** Implementation building block of ProcDispatcher to control waiting and timing.
** This helper encapsulates the loop control logic to separate it from actual
** implementation of timing and waiting (per pthread condition variables).
** It exposes a combined condition (to be used for waiting) plus any further
** controls to manage the operation of the actual queue. The actual tasks to
** be controlled are installed as functors.
**
** @todo WIP-WIP as of 12/2016
**
** @see DispatcherLooper_test
** @see proc-dispatcher.hpp
** @see DispatcherLoop
** @see CommandQueue
**
*/
#ifndef PROC_CONTROL_LOOPER_H
#define PROC_CONTROL_LOOPER_H
#include "lib/error.hpp" ////////TODO needed?
//#include "common/subsys.hpp"
//#include "lib/depend.hpp"
//#include <memory>
//#include <functional>
namespace proc {
namespace control {
// using lib::Symbol;
// using std::bind;
/**
* @todo Type-comment
*/
class Looper
{
public:
Looper()
{ }
/* == diagnostics == */
// size_t size() const ;
// bool empty() const ;
};
////////////////TODO 12/16 currently just fleshing out the API....
}} // namespace proc::control
#endif /*PROC_CONTROL_LOOPER_H*/

7
src/proc/control/proc-dispatcher.cpp
View file

@ -26,6 +26,8 @@
#include "include/logging.h"
#include "proc/control/proc-dispatcher.hpp"
#include "proc/control/command-dispatch.hpp"
#include "proc/control/command-queue.hpp"
#include "proc/control/looper.hpp"
#include "proc/control/session-command-service.hpp"
#include "proc/mobject/session.hpp"
#include "backend/thread-wrapper.hpp"
@ -55,12 +57,17 @@ namespace control {
unique_ptr<SessionCommandService> commandService_;
CommandQueue queue_;
Looper looper_;
public:
DispatcherLoop (Subsys::SigTerm notification)
: ThreadJoinable("Lumiera Session"
, bind (&DispatcherLoop::run, this, notification))
, commandService_(new SessionCommandService(*this))
, queue_()
, looper_()
{
INFO (session, "Proc-Dispatcher running...");
}

10
tests/45controller.tests
View file

@ -115,3 +115,13 @@ END
PLANNED "Command usage aspects III" CommandUse3_test <<END
return: 0
END
PLANNED "Dispatcher loop control logic" DispatcherLooper_test <<END
return: 0
END
PLANNED "Dispatcher command queue" CommandQueue_test <<END
return: 0
END

12
tests/backend/sync-timedwait-test.cpp
View file

@ -54,8 +54,14 @@ namespace test{
* @test timeout feature on condition wait as provided by pthread and accessible
* via the object monitor based locking/waiting mechanism. Without creating
* multiple threads, we engage into a blocking wait, which aborts due to
* setting a timeout. (Note it is discouraged to use the timed wait feature;
* when possible, you should prefer relying on the Lumiera scheduler)
* setting a timeout. Our waiting facility is written such as to invoke
* the condition prior to entering wait state (and consecutively whenever
* awakened). This test switches into wait-with-timeout mode right from
* within this condition check and thus works even while there is no
* other thread and thus an unconditional wait would stall forever.
*
* @note it is discouraged to use the timed wait feature for "timing";
* when possible you should prefer relying on the Lumiera scheduler
*
* @see SyncWaiting_test
* @see sync::Timeout
@ -85,7 +91,7 @@ namespace test{
neverHappens() ///< the "condition test" used for waiting....
{
Lock currentLock(this); // get the Lock recursively
if (!currentLock.isTimedWait()) // right from within the condition test:
if (!currentLock.isTimedWait()) // right from within the condition check:
currentLock.setTimeout(WAIT_mSec); // switch waiting mode to timed wait and set timeout
return false;

89
tests/core/proc/control/command-queue-test.cpp Normal file
View file

@ -0,0 +1,89 @@
/*
CommandQueue(Test) - verify functionality of ProcDispatcher queue component
Copyright (C) Lumiera.org
2016, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
* *****************************************************/
#include "lib/test/run.hpp"
#include "proc/control/command-queue.hpp"
//#include "proc/control/command.hpp"
//#include "proc/control/command-registry.hpp"
//#include "lib/test/event-log.hpp"
//#include "proc/control/test-dummy-commands.hpp"
//#include <cstdlib>
namespace proc {
namespace control {
namespace test {
// using std::function;
// using std::rand;
namespace { // test fixture...
}//(End) test fixture
// typedef shared_ptr<CommandImpl> PCommandImpl;
// typedef HandlingPattern const& HaPatt;
/******************************************************************************//**
* @test verify proper working of queue management used within ProcDispatcher.
* - can enqueue and dequeue command messages
* - handling of priority messages
*
* @see CommandQueue
* @see DispatcherLoop
* @see ProcDispatcher
* @see DispatcherLooper_test
*/
class CommandQueue_test : public Test
{
virtual void
run (Arg)
{
verifyBasics();
}
void
verifyBasics()
{
}
};
/** Register this test class... */
LAUNCHER (CommandQueue_test, "unit controller");
}}} // namespace proc::control::test

89
tests/core/proc/control/dispatcher-looper-test.cpp Normal file
View file

@ -0,0 +1,89 @@
/*
DispatcherLooper(Test) - verify loop control and timing functionality of ProcDispatcher
Copyright (C) Lumiera.org
2016, Hermann Vosseler <Ichthyostega@web.de>
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2 of
the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
* *****************************************************/
#include "lib/test/run.hpp"
#include "proc/control/command-queue.hpp"
//#include "proc/control/command.hpp"
//#include "proc/control/command-registry.hpp"
//#include "lib/test/event-log.hpp"
//#include "proc/control/test-dummy-commands.hpp"
//#include <cstdlib>
namespace proc {
namespace control {
namespace test {
// using std::function;
// using std::rand;
namespace { // test fixture...
}//(End) test fixture
// typedef shared_ptr<CommandImpl> PCommandImpl;
// typedef HandlingPattern const& HaPatt;
/******************************************************************************//**
* @test verify encapsulated control logic of ProcDispatcher.
* - fusing of conditions for the pthread waiting condition
* - detection and handling of work states
* - management of builder run triggers
*
* @see proc::control::Looper
* @see DispatcherLoop
* @see CommandQueue_test
*/
class DispatcherLooper_test : public Test
{
virtual void
run (Arg)
{
verifyBasics();
}
void
verifyBasics()
{
}
};
/** Register this test class... */
LAUNCHER (DispatcherLooper_test, "unit controller");
}}} // namespace proc::control::test

26
wiki/renderengine.html
View file

@ -5222,11 +5222,35 @@ Besides, they provide an __inward interface__ for the [[ProcNode]]s, enabling th
[img[Asset Classess|uml/fig131077.png]]
{{red{Note 3/2010}}} it is very unlikely we'll organise the processing nodes as a class hierarchy. Rather it looks like we'll get several submodules/special capabilities configured in within the Builder</pre>
</div>
<div title="ProcDispatcher" creator="Ichthyostega" modifier="Ichthyostega" created="201612140406" tags="def SessionLogic draft" changecount="1">
<div title="ProcDispatcher" creator="Ichthyostega" modifier="Ichthyostega" created="201612140406" modified="201612151859" tags="def spec SessionLogic draft" changecount="3">
<pre>//The guard and coordinator of any operation within the session subsystem.//
The session and related components work effectively single threaded. Any tangible operation on the session data structure has to be enqueued as [[command|CommandHandling]] into the dispatcher. Moreover, the [[Builder]] is triggered from the ProcDispatcher; and while the Builder is running, any command processing is halted. The Builder in turn creates or reshapes the processing nodes network, and the changed network is brought into operation with a //transactional switch// -- while render processes on this processing network operate unaffected and essentially multi-threaded.
Enqueueing commands through the {{{SessionCommandFacade}}} into the ProcDispatcher is the official way to cause changes to the session. And the running state of the ProcDispatcher is equivalent with the running state of the //session subsystem as a whole.//
!Requirements
To function properly as action coordinator of the session subsystem, the dispatcher has to fulfil multiple demands
;enqueue
:accept and enqueue command messages concurrently, any time, without blocking the caller
:*FIFO for //regular commands//
:*LIFO for //priority requests//
;process
:dequeue and process entries sequentially
;sleep
:work continuously until queue is empty, then enter wait state
;check point
:invoke a well defined check point reliably non blocking (&quot;ensure to make progress&quot;)
:* when?
:** after each command
:** regularily whle idle
:* why?
:** ensure the Builder runs regularly
:** respond reliably to shutdown request
;manage
:care for rectifying entries in the queue
:* ensure they //match// current session, discard obsoleted requests
:* //aggregate// similar requests
:* //supersede// by newer commands of a certain kind
</pre>
</div>
<div title="ProcLayer" modifier="Ichthyostega" created="200708100333" modified="200708100338" tags="def">

47
wiki/thinkPad.ichthyo.mm
View file

@ -11005,8 +11005,8 @@
</node>
<node CREATED="1481777355747" ID="ID_1804595708" MODIFIED="1481777364326" TEXT="Subsystem-&gt;end">
<node CREATED="1481777368330" ID="ID_1933237483" MODIFIED="1481777374277" TEXT="Halte-Nachricht"/>
<node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1481777374801" ID="ID_1844558240" MODIFIED="1481778660075" TEXT="sicherstellen, da&#xdf; Loop anh&#xe4;lt">
<arrowlink COLOR="#f70841" DESTINATION="ID_1748096848" ENDARROW="Default" ENDINCLINATION="-200;-90;" ID="Arrow_ID_506637666" STARTARROW="None" STARTINCLINATION="-132;97;"/>
<node BACKGROUND_COLOR="#fdfdcf" COLOR="#ff0000" CREATED="1481777374801" ID="ID_1844558240" MODIFIED="1481826297245" TEXT="sicherstellen, da&#xdf; Loop anh&#xe4;lt">
<arrowlink COLOR="#f70841" DESTINATION="ID_1748096848" ENDARROW="Default" ENDINCLINATION="-353;-77;" ID="Arrow_ID_506637666" STARTARROW="None" STARTINCLINATION="-200;38;"/>
<icon BUILTIN="flag-pink"/>
</node>
<node CREATED="1481777397542" ID="ID_1147135932" MODIFIED="1481778447806" TEXT="DispatcherLoop stirbt"/>
@ -11016,7 +11016,32 @@
</node>
</node>
<node CREATED="1481778538165" HGAP="37" ID="ID_522398894" MODIFIED="1481778549049" TEXT="ProcDispatcher" VSHIFT="12">
<node CREATED="1481778549940" ID="ID_676848252" MODIFIED="1481778556025" TEXT="DispatcherLoop">
<node CREATED="1481826274018" ID="ID_1916296972" MODIFIED="1481826277691" TEXT="Requirements">
<node CREATED="1481826329819" ID="ID_1238318698" MODIFIED="1481826431105" TEXT="enqueue commands concurrently">
<node CREATED="1481827297122" ID="ID_860095678" MODIFIED="1481827311268" TEXT="FIFO for regular commands"/>
<node CREATED="1481827312024" ID="ID_850193431" MODIFIED="1481827318187" TEXT="LIFO for priority requests"/>
</node>
<node CREATED="1481826431861" ID="ID_328583048" MODIFIED="1481826440935" TEXT="process sequentially"/>
<node CREATED="1481826441884" ID="ID_952327020" MODIFIED="1481826446791" TEXT="until queue is empty"/>
<node CREATED="1481826997930" ID="ID_576341056" MODIFIED="1481827018171" TEXT="invoke check point">
<node CREATED="1481827040748" ID="ID_406205627" MODIFIED="1481827045172" TEXT="when">
<icon BUILTIN="help"/>
<node CREATED="1481827019615" ID="ID_1169845292" MODIFIED="1481827024402" TEXT="after each command"/>
<node CREATED="1481827024942" ID="ID_137101226" MODIFIED="1481827033713" TEXT="regularily whle idle"/>
</node>
<node CREATED="1481827051787" ID="ID_1911969568" MODIFIED="1481827055340" TEXT="why">
<icon BUILTIN="help"/>
<node CREATED="1481827057618" ID="ID_80559422" MODIFIED="1481827068540" TEXT="ensure Builder runs"/>
<node CREATED="1481827109643" ID="ID_76492776" MODIFIED="1481827126189" TEXT="respond to shutdown request"/>
</node>
</node>
<node CREATED="1481827548073" ID="ID_690689259" MODIFIED="1481827556820" TEXT="manage entries">
<node CREATED="1481827558336" ID="ID_1026688096" MODIFIED="1481827646856" TEXT="match current session"/>
<node CREATED="1481827647491" ID="ID_1849886325" MODIFIED="1481827652111" TEXT="aggregate similar"/>
<node CREATED="1481827652539" ID="ID_313823253" MODIFIED="1481827657846" TEXT="supersede"/>
</node>
</node>
<node CREATED="1481778549940" HGAP="35" ID="ID_676848252" MODIFIED="1481828600299" TEXT="DispatcherLoop">
<icon BUILTIN="pencil"/>
<node CREATED="1481778741546" ID="ID_684867533" MODIFIED="1481778755694" TEXT="&#xf6;ffnet Session-Interface">
<icon BUILTIN="button_ok"/>
@ -11024,13 +11049,23 @@
<node CREATED="1481778565298" ID="ID_1803510423" MODIFIED="1481778569181" TEXT="Schleifen-Logik">
<node CREATED="1481778570153" ID="ID_6904207" MODIFIED="1481778579395" TEXT="beruht auf CondVar / wait"/>
</node>
<node CREATED="1481778590790" ID="ID_1748096848" MODIFIED="1481778652116" TEXT="Anhalten">
<linktarget COLOR="#f70841" DESTINATION="ID_1748096848" ENDARROW="Default" ENDINCLINATION="-200;-90;" ID="Arrow_ID_506637666" SOURCE="ID_1844558240" STARTARROW="None" STARTINCLINATION="-132;97;"/>
<node CREATED="1481778590790" ID="ID_1748096848" MODIFIED="1481826297245" TEXT="Anhalten">
<linktarget COLOR="#f70841" DESTINATION="ID_1748096848" ENDARROW="Default" ENDINCLINATION="-353;-77;" ID="Arrow_ID_506637666" SOURCE="ID_1844558240" STARTARROW="None" STARTINCLINATION="-200;38;"/>
<node CREATED="1481778666820" ID="ID_1860590145" MODIFIED="1481778688685" TEXT="trigger-Variable mustHalt_"/>
</node>
</node>
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1481778708207" ID="ID_1311208726" MODIFIED="1481778716670" TEXT="Builder-Steuerung">
<node BACKGROUND_COLOR="#eee5c3" COLOR="#990000" CREATED="1481778708207" HGAP="48" ID="ID_1311208726" MODIFIED="1481828597227" TEXT="Builder-Steuerung" VSHIFT="-5">
<icon BUILTIN="flag-yellow"/>
<node CREATED="1481828478741" ID="ID_1706868067" MODIFIED="1481828497838" TEXT="Hysterese"/>
<node CREATED="1481828498618" ID="ID_321199314" MODIFIED="1481828519539" TEXT="nach neuem Command, mit kleiner Verz&#xf6;gerung"/>
<node CREATED="1481828520176" ID="ID_239973202" MODIFIED="1481828532570" TEXT="bei voller Schlange mit Toleranzschwelle"/>
<node CREATED="1481828568129" ID="ID_295162940" MODIFIED="1481828574412" TEXT="Builder-Lauf ist monolithisch"/>
</node>
<node CREATED="1481828583551" ID="ID_436508747" MODIFIED="1481828608672" TEXT="Aufbau">
<node CREATED="1481828611347" ID="ID_160907866" MODIFIED="1481828614071" TEXT="Front-End"/>
<node CREATED="1481828614827" ID="ID_1752707995" MODIFIED="1481828622958" TEXT="DispatcherLoop PImpl"/>
<node CREATED="1481828624042" ID="ID_1970372601" MODIFIED="1481828635748" TEXT="Looper f&#xfc;r Schleifen-Logik"/>
<node CREATED="1481828639584" ID="ID_1344182776" MODIFIED="1481828648402" TEXT="CommandQueue"/>
</node>
</node>
</node>