Job and JobClosure now located in the backend

- adjust namespaces
- fix imports
- forward the failure reason to the JobClosure implementation

src/backend/engine/job.cpp

@@ -23,8 +23,8 @@
 
 /** @file job.cpp 
  ** Implementation of render job invocation.
- ** Within this translation unit, the actual invocation of a frame rendering
- ** job takes place, after reconstruction of the job's execution environment (closure).
+ ** Within this translation unit, the actual invocation of a frame rendering job
+ ** takes place, after reconstruction of the job's execution environment (closure).
  ** 
  ** @see JobTicket
  ** @see ProcNode
@@ -33,11 +33,10 @@
  */
 
 
-#include "proc/engine/job.hpp"
-#include "proc/engine/job-ticket.hpp"
+#include "backend/engine/job.h"
 
 
-namespace proc {
+namespace backend {
 namespace engine {
   
   namespace { // Details...
@@ -79,9 +78,9 @@ namespace engine {
   
   
   void
-  Job::signalFailure()  const
+  Job::signalFailure (JobFailureReason reason)  const
   {
-    myClosure(this).signalFailure (parameter);
+    myClosure(this).signalFailure (parameter, reason);
   }
   
   
@@ -110,10 +109,10 @@ namespace engine {
   }
   
   
-}} // namespace proc::engine
+}} // namespace backend::engine
 
 namespace {
-  using proc::engine::Job;
+  using backend::engine::Job;
     
   inline Job& 
   forwardInvocation (lumiera_jobDefinition& jobDef)
@@ -137,9 +136,9 @@ lumiera_job_invoke  (LumieraJobDefinition jobDef)
 }
 
 void
-lumiera_job_failure (LumieraJobDefinition jobDef, JobFailureReason)
+lumiera_job_failure (LumieraJobDefinition jobDef, JobFailureReason reason)
 {
   REQUIRE (jobDef);
-  forwardInvocation(*jobDef).signalFailure();   ////TODO forward the JobFailureReason parameter
+  forwardInvocation(*jobDef).signalFailure(reason);
 }
 }

src/backend/engine/job.h

@@ -1,5 +1,5 @@
 /*
-  JOB.hpp  -  render job closure
+  JOB.h  -  render job closure
 
   Copyright (C)         Lumiera.org
     2012,               Hermann Vosseler <Ichthyostega@web.de>
@@ -21,15 +21,38 @@
 */
 
 
-#ifndef PROC_ENGINE_JOB_H
-#define PROC_ENGINE_JOB_H
+/** @file job.h
+ ** Definition of a render job.
+ ** Jobs are defined within Proc-Layer and passed to the scheduler in the Back-end
+ ** for time bound invocation. This header defines the data structures used to describe
+ ** a job, and the basic data structures used by the scheduler to keep track of individual
+ ** jobs. Moreover, within the C++ part of this header, some classes are layered on top
+ ** of these data structures; especially the JobClosure ABC describes the \em generic part
+ ** of each job, while the "moving parts" are embedded within the lumiera_jobParameter.
+ ** 
+ ** A render job is a parameterless function, ready to be invoked by the scheduler..
+ ** Since every non trivial job actually needs some parameters (at least a frame number)
+ ** and relies on additional definitions and data structures, a \em closure is created
+ ** to make these dependencies explicit and opaque for the scheduler. The actual
+ ** job invocation is forwarded to a virtual function JobClosure#invokeJobOperation(JobParameter),
+ ** which is defined "somewhere" in a subclass and remains opaque for the scheduler;
+ ** the \link proc::engine::Dispatcher frame dispatcher \endlink takes care to configure
+ ** each job descriptor with the correct pointer to a concrete closure prior to handing
+ ** the job over to the scheduler.
+ ** 
+ ** @see SchedulerFrontend
+ ** @see JobTicket
+ **
+ */
+
+
+#ifndef BACKEND_ENGINE_JOB_H
+#define BACKEND_ENGINE_JOB_H
 
-///////////////////////////////////////////////////////////////////TICKET #926 : Job descriptor belongs into backend
 
 #include "lib/llist.h"
 #include "lib/hash-value.h"
-
-#include <gavl/gavl.h>
+#include "lib/time.h"
 
 
 /** opaque ID attached to each individual job invocation.
@@ -61,8 +84,9 @@ enum JobKind
     META_JOB   ///< render process self organisation
   };
 
+
 /**
- * @todo the kinds of failures that are possible
+ * @todo find out about the possible kinds of failure
  */
 enum JobFailureReason
   {
@@ -107,15 +131,12 @@ typedef lumiera_jobDefinition* LumieraJobDefinition;
 
 
 /**
+ * Description of a job. Jobs are passed by the Proc-Layer to the Back-End. 
  * 
- * \brief Description of a job
- * 
- * This describes a job which is passed by the Proc-Layer to the Back-End. 
- * 
- * descriptor record used by the scheduler to organise job invocation.
- * The actual job's definition, i.e. the invocation parameter and
- * the closure necessary to invoke the job as a function
- * is embedded (by value) into this descriptor.
+ * This descriptor record is used by the scheduler to organise job invocation.
+ * The actual job's definition, i.e. the invocation parameter and the closure
+ * necessary to invoke the job as a function is embedded (by value)
+ * into this descriptor.
  * 
  * @remarks all fields of interest only to the backend,
  *       except #jobDefinition, which is provided by and of
@@ -127,10 +148,10 @@ typedef lumiera_jobDefinition* LumieraJobDefinition;
  */
 struct lumiera_jobDescriptor_struct
   {
-    gavl_time_t when; /// deadline (real wall clock time)
+    gavl_time_t deadline;                ///< given in real wall clock time
     JobState jobState;
     
-    lumiera_jobDefinition jobDefinition; /// of interest only to Proc-Layer
+    lumiera_jobDefinition jobDefinition; ///< of interest only to Proc-Layer
     
     /* == Job prerequisites == */
     LList waiting;
@@ -149,12 +170,10 @@ typedef lumiera_jobDescriptor* LumieraJobDescriptor;
 
 #ifdef __cplusplus  /* ============== C++ Interface ================= */
 
-#include "lib/error.hpp"
-#include "lib/time/timevalue.hpp"
 
 
 
-namespace proc {
+namespace backend {
 namespace engine {
   
   using lib::time::TimeValue;
@@ -184,11 +203,11 @@ namespace engine {
       virtual ~JobClosure();     ///< this is an interface
       
       
-      virtual void invokeJobOperation (JobParameter parameter)  =0;
-      virtual void signalFailure      (JobParameter parameter)  =0;
+      virtual void invokeJobOperation (JobParameter parameter)   =0;
+      virtual void signalFailure (JobParameter,JobFailureReason) =0;
       
-      virtual JobKind getJobKind()  const                       =0;
-      virtual bool verify (Time nominalJobTime)  const          =0;
+      virtual JobKind getJobKind()  const                        =0;
+      virtual bool verify (Time nominalJobTime)  const           =0;
     };
   
   
@@ -225,8 +244,8 @@ namespace engine {
       // using standard copy operations
       
       
-      void triggerJob()    const;
-      void signalFailure() const;
+      void triggerJob()                     const;
+      void signalFailure (JobFailureReason) const;
       
       
       Time
@@ -246,7 +265,7 @@ namespace engine {
     };
   
   
-}} // namespace proc::engine
+}} // namespace backend::engine
 
 
 

src/proc/engine/calc-plan-continuation.hpp

@@ -42,6 +42,8 @@ namespace proc {
 namespace engine {
   
 //  using std::tr1::function;
+  using backend::engine::JobParameter;
+  using backend::engine::JobClosure;
   using mobject::ModelPort;
 //  using lib::time::TimeSpan;
 //  using lib::time::FSecs;
@@ -94,7 +96,7 @@ namespace engine {
       
       
       void
-      signalFailure (JobParameter parameter)
+      signalFailure (JobParameter parameter, JobFailureReason reason)
         {
           UNIMPLEMENTED ("what needs to be done when a planning continuation cant be invoked?");
         }

src/proc/engine/job-planning.hpp

@@ -68,6 +68,7 @@
 #include "backend/engine/job.h"
 #include "proc/engine/job-ticket.hpp"
 #include "proc/engine/frame-coord.hpp"
+#include "lib/time/timevalue.hpp"
 #include "lib/iter-explorer.hpp"
 #include "lib/iter-adapter.hpp"
 #include "lib/util.hpp"
@@ -79,6 +80,7 @@ namespace engine {
   
   namespace error = lumiera::error;
   
+  using lib::time::TimeValue;
   using util::unConst;
   using util::isnil;
   

src/proc/engine/job-ticket.cpp

@@ -43,7 +43,8 @@ namespace engine {
   
 //  using mobject::Placement;
 //  using mobject::session::Effect;
-  
+using backend::engine::JobParameter;
+using backend::engine::JobClosure;
   
   
   
@@ -76,7 +77,7 @@ namespace engine {
       
       
       void
-      signalFailure (JobParameter parameter)
+      signalFailure (JobParameter parameter, JobFailureReason reason)
         {
           UNIMPLEMENTED ("what needs to be done when a job cant be invoked?");
         }

src/proc/engine/job-ticket.hpp

@@ -46,6 +46,7 @@ namespace engine {
 //using lib::time::Duration;
 //using lib::time::FSecs;
 //using lib::time::Time;
+using backend::engine::Job;
 using lib::LinkedElements;
 using lib::OrientationIndicator;
 using util::isnil;

tests/core/backend/engine/scheduler-interface-test.cpp

@@ -37,8 +37,8 @@ namespace test {
   using lib::time::Duration;
   using lib::time::FSecs;
   
-  using proc::engine::JobClosure;
-  using proc::engine::JobParameter;
+  using backend::engine::JobClosure;
+  using backend::engine::JobParameter;
   
   
   namespace { // test fixture: a dummy job operation...
@@ -53,7 +53,7 @@ namespace test {
           }
         
         void
-        signalFailure (JobParameter)
+        signalFailure (JobParameter,JobFailureReason)
           {
             NOTREACHED ("Job failure is not subject of this test");
           }