Scheduler.h

Go to the documentation of this file.

/*
 *
 *  Scheduler class for Win32/CSL/Lua
 *  Header
 *
 *  Brent Lehman
 *  28 November 2003
 *
 *
 */


// Designed to be run in the program's main thread.
//
// Here's what I have in mind for its use with CSL and Lua:
// 1. Main program does whatever initialization it needs
// 2. Main program instantiates Scheduler, giving it a script
//     file and making the Scheduler a global property within
//     the script so code within the script can access it
// 3. Scheduler runs Lua script
// 4. Main body of Lua script adds events to Scheduler's queue
// 5. Lua script returns
// 6. Scheduler enters event loop, exiting when queue is empty
// 7. Events take the form of calls to functions in Lua script;
//     these functions do whatever they need to do, which might
//     include adding new events to the queue
//
// Note that the Lua script functions are still in memory and
// available for execution after the script returns in step 5.
//
// Each event has a time value that specifies when it should
// occur.  These time values are relative to the beginning of
// the performance.  When the Scheduler receives an event for 
// addition to the queue that is out of chronological order 
// with respect to the other events on the queue, it backtracks 
// from the end until it finds the right spot to add the event.
// The Scheduler also offers a utility for adding a group of 
// events that is faster per event than calling the add
// function for each event would be.
//
// Since event times are specified relative to the beginning of
// the performance rather than relative to the last event, a 
// script's various functions can add events independently;
// that is, no function need worry about the fact that some
// other function's event might currently be last on the queue.
// Every function can pretend that it's the only one generating
// events.
//
// Thus, some functions that add events need to know what the
// current performance time is.  This is mildly annoying
// because musicians using this facility will want to do the
// least possible amount of housekeeping.  Another approach
// would be to have multiple "voices", and have each event know
// which voice it belongs to.  Then event times could be 
// relative to the last event in that same voice and script 
// functions wouldn't need to keep track of time.  This just 
// adds a different kind of housekeeping, though, and could be 
// said to be a less elegant solution because of the extra data
// each event would need to carry around.


#ifndef WIN32_LEAN_AND_MEAN
#define WIN32_LEAN_AND_MEAN 
#endif
//#include    "windows.h"
#include   "mmsystem.h"
#include "CSL_Kernel.h"


namespace csl {

struct SchedulerEvent
{
  unsigned int time;
  char* action;
  int action_size;
  SchedulerEvent* prev_event;
  SchedulerEvent* next_event;
};


class Scheduler
{

  SchedulerEvent* events;
  SchedulerEvent* next_event;
  SchedulerEvent* last_event;
  bool* space_free;
  int allocated_spaces;
  int filled_spaces;
  int first_free_space;
  int new_chunk_size;
  volatile bool running;
  volatile unsigned int earliest_possible_event_time;
  int dawn_of_time;
  int unsigned now;
  volatile int now_precision;

  int _find_free_space();

public:

  Scheduler(int starting_size=64, int adding_size=64);
 ~Scheduler();

  void add_event(unsigned int time, char* action);
  void add_events(unsigned int* times, char** actions, int num_events);

  void go();
  void stop();

  bool is_running();
  unsigned int current_time();
  int resolution();

};

}

---