diff --git a/src/backend/engine/job.cpp b/src/backend/engine/job.cpp index 8a5ac136b..2ddd6d173 100644 --- a/src/backend/engine/job.cpp +++ b/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); } } diff --git a/src/backend/engine/job.h b/src/backend/engine/job.h index b69111f17..2c1025569 100644 --- a/src/backend/engine/job.h +++ b/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 @@ -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 +#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 diff --git a/src/proc/engine/calc-plan-continuation.hpp b/src/proc/engine/calc-plan-continuation.hpp index 1432e1aa2..b41cfb291 100644 --- a/src/proc/engine/calc-plan-continuation.hpp +++ b/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?"); } diff --git a/src/proc/engine/job-planning.hpp b/src/proc/engine/job-planning.hpp index 5b458ade8..f57c18812 100644 --- a/src/proc/engine/job-planning.hpp +++ b/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; diff --git a/src/proc/engine/job-ticket.cpp b/src/proc/engine/job-ticket.cpp index e5bec3783..a5a809b09 100644 --- a/src/proc/engine/job-ticket.cpp +++ b/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?"); } diff --git a/src/proc/engine/job-ticket.hpp b/src/proc/engine/job-ticket.hpp index 4dc62d19a..dc6201a47 100644 --- a/src/proc/engine/job-ticket.hpp +++ b/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; diff --git a/tests/core/backend/engine/scheduler-interface-test.cpp b/tests/core/backend/engine/scheduler-interface-test.cpp index 5e018b075..b2213eb51 100644 --- a/tests/core/backend/engine/scheduler-interface-test.cpp +++ b/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"); }