Simpler and documented Engine main loop interface.

git-svn-id: http://svn.drobilla.net/lad/trunk/ingen@3150 a436a847-0d15-0410-975c-d299462d15a1

4 files changed, 32 insertions, 47 deletions

diff --git a/src/engine/Engine.cpp b/src/engine/Engine.cpp
index 6a3d25a6..b57fa542 100644
--- a/src/engine/Engine.cpp
+++ b/src/engine/Engine.cpp
@@ -65,7 +65,6 @@ Engine::Engine(Ingen::Shared::World* a_world)
 	, _node_factory(new NodeFactory(a_world))
 	, _message_context(new MessageContext(*this))
 	, _buffer_factory(new BufferFactory(*this, a_world->uris()))
-	//, _buffer_factory(NULL)
 	, _control_bindings(new ControlBindings(*this))
 	, _quit_flag(false)
 	, _activated(false)
@@ -105,46 +104,22 @@ Engine::engine_store() const
 }
 
 
-int
-Engine::main()
+void
+Engine::quit()
 {
-	Raul::Thread::get().set_context(THREAD_POST_PROCESS);
-
-	// Loop until quit flag is set
-	while (!_quit_flag) {
-		nanosleep(&main_rate, NULL);
-		main_iteration();
-	}
-	info << "Finished main loop" << endl;
-
-	deactivate();
-
-	return 0;
+	_quit_flag = true;
 }
 
-
-/** Run one iteration of the main loop.
- *
- * NOT realtime safe (this is where deletion actually occurs)
- */
 bool
 Engine::main_iteration()
 {
 	_post_processor->process();
 	_maid->cleanup();
-
 	return !_quit_flag;
 }
 
 
 void
-Engine::quit()
-{
-	_quit_flag = true;
-}
-
-
-void
 Engine::add_event_source(SharedPtr<EventSource> source)
 {
 	_event_sources.insert(source);
diff --git a/src/engine/Engine.hpp b/src/engine/Engine.hpp
index c612e62c..c2756e11 100644
--- a/src/engine/Engine.hpp
+++ b/src/engine/Engine.hpp
@@ -18,7 +18,6 @@
 #ifndef INGEN_ENGINE_ENGINE_HPP
 #define INGEN_ENGINE_ENGINE_HPP
 
-#include <cassert>
 #include <set>
 #include <vector>
 
@@ -48,16 +47,15 @@ class ProcessContext;
 class ProcessSlave;
 
 
-/** The main class for the Engine.
- *
- * This is a (GoF) facade for the engine.  Pointers to all components are
- * available for more advanced control than this facade allows.
- *
- * Most objects in the engine have (directly or indirectly) a pointer to the
- * Engine they are a part of.
- *
- * \ingroup engine
- */
+/**
+   The engine which executes the process graph.
+
+   This is a simple class that provides pointers to the various components
+   that make up the engine implementation.  In processes with a local engine,
+   it can be accessed via the Ingen::Shared::World.
+
+  \ingroup engine
+*/
 class Engine : public boost::noncopyable
 {
 public:
@@ -65,13 +63,29 @@ public:
 
 	virtual ~Engine();
 
-	virtual int  main();
-	virtual bool main_iteration();
+	virtual bool activate();
+	virtual void deactivate();
 
+	/**
+	   Indicate that a quit is desired
+
+	   This function simply sets a flag which affects the return value of
+	   main iteration, it does not actually force the engine to stop running
+	   or block.  The code driving the engine is responsible for stopping
+	   and cleaning up when main_iteration returns false.
+	*/
 	virtual void quit();
 
-	virtual bool activate();
-	virtual void deactivate();
+	/**
+	   Run a single iteration of the main context.
+
+	   The main context performs housekeeping duties like collecting garbage.
+	   This should be called regularly, e.g. a few times per second.
+	   The return value indicates whether execution should continue; i.e. if
+	   false is returned, the caller should cease calling main_iteration()
+	   and stop the engine.
+	*/
+	virtual bool main_iteration();
 
 	virtual void process_events(ProcessContext& context);
 
diff --git a/src/engine/ThreadManager.hpp b/src/engine/ThreadManager.hpp
index 2966fb3e..45ad410b 100644
--- a/src/engine/ThreadManager.hpp
+++ b/src/engine/ThreadManager.hpp
@@ -27,7 +27,6 @@ namespace Ingen {
 enum ThreadID {
 	THREAD_PRE_PROCESS,
 	THREAD_PROCESS,
-	THREAD_POST_PROCESS,
 	THREAD_MESSAGE,
 };
 
diff --git a/src/engine/tuning.hpp b/src/engine/tuning.hpp
index 5421d7b3..1cf6ed1c 100644
--- a/src/engine/tuning.hpp
+++ b/src/engine/tuning.hpp
@@ -31,9 +31,6 @@ static const size_t post_processor_queue_size  = 1024;
 static const size_t maid_queue_size            = 1024;
 static const size_t message_context_queue_size = 1024;
 
-//static const timespec main_rate     = { 0, 500000000 }; // 1/2 second
-static const timespec main_rate       = { 0, 125000000 }; // 1/8 second
-
 static const size_t event_bytes_per_frame = 4;