From aca90f7ce8561209baf21e8695250ce0c860ce62 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Sat, 12 Jan 2013 14:36:01 +0100 Subject: [PATCH] DONE: mechanics of job planning --- src/proc/engine/job-planning.hpp | 81 +++++++++++++++++++------------- 1 file changed, 49 insertions(+), 32 deletions(-) diff --git a/src/proc/engine/job-planning.hpp b/src/proc/engine/job-planning.hpp index 4dcfb61e2..c8431a6a9 100644 --- a/src/proc/engine/job-planning.hpp +++ b/src/proc/engine/job-planning.hpp @@ -20,25 +20,42 @@ */ +/** @file job-planning.hpp + ** The "mechanics" of discovering and planning frame calculation jobs. + ** This is a rather abstract chunk of code, dealing especially with the technicalities + ** of \em organising the discovery of prerequisites and of joining all the discovered operations + ** into a sequence of planning steps. The net result is to present a sequence of job planing + ** to the user, while actually encapsulating a depth-first tree exploration, which proceeds on demand. + ** + ** \par participating elements + ** All of these job planning operations are implemented on top of the JobTicket. This is where to look + ** for "actual" implementation code. Here, within this header, the following entities cooperate to + ** create a simple sequence out of this implementation level tasks: + ** - JobPlanningSequence is the entry point for client code: it allows to generate a sequence of jobs + ** - JobPlanning is a view on top of all the collected planning information for a single job + ** - PlanningState is an iterator, successively exposing a sequence of JobPlanning views + ** - #expandPrerequisites(JobPlanning cons&) is the operation to explore further prerequisite Jobs + ** - PlanningStepGenerator yields the underlying "master beat": a sequence of frame locations to be planned + ** + ** @see DispatcherInterface_test simplified usage examples + ** @see JobTicket + ** @see Dispatcher + ** @see EngineService + ** + */ + #ifndef PROC_ENGINE_JOB_PLANNING_H #define PROC_ENGINE_JOB_PLANNING_H #include "proc/common.hpp" -//#include "proc/state.hpp" #include "proc/engine/job.hpp" #include "proc/engine/job-ticket.hpp" -//#include "proc/engine/time-anchor.hpp" #include "proc/engine/frame-coord.hpp" -//#include "lib/time/timevalue.hpp" -//#include "lib/time/timequant.hpp" -//#include "lib/meta/function.hpp" -#include "lib/iter-adapter.hpp" #include "lib/iter-explorer.hpp" -//#include "lib/linked-elements.hpp" +#include "lib/iter-adapter.hpp" #include "lib/util.hpp" -//#include namespace proc { @@ -46,17 +63,11 @@ namespace engine { namespace error = lumiera::error; -//using lib::time::TimeSpan; -//using lib::time::Duration; -//using lib::time::FSecs; -//using lib::time::Time; -//using lib::LinkedElements; - using util::isnil; using util::unConst; -// -//class ExitNode; + using util::isnil; + + - /** * View on the execution planning for a single calculation step. * When this view-frontend becomes accessible, behind the scenes all @@ -73,7 +84,7 @@ namespace engine { * @remarks on the implementation level, JobPlanning is used as "state core" * for a PlanningState iterator, to visit and plan subsequently all * the individual operations necessary to render a timeline chunk. - */ + */ class JobPlanning { JobTicket::ExplorationState plannedOperations_; @@ -96,7 +107,7 @@ namespace engine { , point_to_calculate_(requestedFrame) { } - // using the standard copy operations + // using the standard copy operations /** cast and explicate this job planning information @@ -114,7 +125,7 @@ namespace engine { /** build a new JobPlanning object, - * set to explore the prerequisites + * set to explore the prerequisites * at the given planning situation */ JobPlanning @@ -162,13 +173,15 @@ namespace engine { iterNext (JobPlanning & plan) { plan.plannedOperations_.pullNext(); - } + } }; - + /** + * iterator, exposing a sequence of JobPlanning elements + */ class PlanningState : public lib::IterStateWrapper { @@ -202,7 +215,7 @@ namespace engine { integrate (startingPoint, this->stateCore()); return *this; } - + PlanningState & usingSequence (PlanningState const& prerequisites) { @@ -220,7 +233,7 @@ namespace engine { /** Extension point to be picked up by ADL. * Provides access for the JobPlanningSequence - * for combining and expanding partial results. + * for combining and expanding partial results. */ friend PlanningState& build (PlanningState& attachmentPoint) @@ -271,7 +284,8 @@ namespace engine { virtual JobTicket& accessJobTicket (ModelPort, TimeValue nominalTime) =0; }; - + + /** * Generate a sequence of starting points for Job planning, * based on the underlying frame grid. This sequence will be @@ -338,25 +352,26 @@ namespace engine { iterNext (PlanningStepGenerator & gen) { gen.currentLocation_ = gen.locationGenerator_->getNextFrame (gen.currentLocation_); - } + } }; + /* type definitions for building the JobPlaningSequence */ typedef PlanningState (*SIG_expandPrerequisites) (JobPlanning const&); typedef lib::IterExplorer JobPlanningChunkStartPoint; - + typedef JobPlanningChunkStartPoint::FlatMapped::Type ExpandedPlanningSequence; /** * This iterator represents a pipeline to pull planned jobs from. - * For dispatching individual frame jobs for rendering, this pipeline is - * generated and internally wired such as to interpret the render node definitions. + * To dispatch individual frame jobs for rendering, this pipeline is generated + * and wired internally such as to interpret the render node definitions. * * \par Explanation of the structure * @@ -375,8 +390,10 @@ namespace engine { * - this basic frame grid is generated by the PlanningStepGenerator, which is * effectively backed by the Dispatcher and thus the render node model. * - * - * @todo 6/12 WIP-WIP-WIP how to prepare jobs for scheduling + * @remarks JobPlanningSequence is a monad, and the operation to explore the prerequisites + * is applied by the \c >>= (monad flat map operation). This approach allows us + * to separate the technicalities of exhausting tree exploration from the actual + * "business code" to deal with frame job dependencies */ class JobPlanningSequence : public ExpandedPlanningSequence @@ -387,9 +404,9 @@ namespace engine { : ExpandedPlanningSequence( JobPlanningChunkStartPoint( PlanningStepGenerator(startPoint,stopPoint,locator)) + >>= expandPrerequisites) // "flat map" (monad operation) { } - };