// Scheduler.h

#ifndef dial__Scheduler_H
#define dial__Scheduler_H

// David Adams
// September 2002
//
// This abstract base class defines the user interface for
// a DIAL scheduler.

#include <vector>
#include <iosfwd>
#include "dial_job/JobId.h"
#include "dial_job/JobIdList.h"
#include "dial_job/Job.h"

class XmlElement;
class PThreadMutex;

namespace dial {

class JobRepository;

class Scheduler {

public:  // typedefs

  // Pointer to a function to create a scheduler from an XML element.
  typedef Scheduler* (*Creator) (const XmlElement&);

  // Creator name.
  typedef std::string CreatorName;

  // List of Creator names.
  typedef std::vector<CreatorName> CreatorList;

public:  // static functions

  // Create a scheduler from an XML description.
  // Caller is responsible for managing the scheduler.
  // The creator is selected using ele.name().
  static Scheduler* create(const XmlElement& ele);

  // Register a creator.
  // Returns 0 for success.
  // Fails if name is already used for a different creator.
  static int register_creator(CreatorName name, Creator pfun);

  // Return the list of registered creator names.
  static const CreatorList& creators();

  // Return if a creator name is registered.
  static bool has_creator(CreatorName name);

public:  // non-const functions

  // Destructor.
  virtual ~Scheduler();

  // Add a task and build it for an application.
  // Returns 0 if no build is required or a job is created to
  // build the task.
  // Returns nonzero if the scheduler does not support this action.
  // Use task_job() to fetch the ID of the build job.
  // Default returns 99.
  virtual int add_task(const Application& app,
                       const Task& tsk);

  // Remove a task build.
  // Kills task job if active.
  // Typically called after a build fails and before retry.
  // Returns 0 for success.
  // Default returns 99.
  virtual int remove_task(const Application& app,
                          const Task& tsk);

  // Submit a job.
  // Returns invalid ID if submission fails.
  virtual JobId submit(
    const Application& app,
    const Task& tsk,
    const dset::Dataset& dst,
    const JobPreferences& prf =JobPreferences::default_instance()
  ) =0;

  // Start a job.
  // Returns zero if the job was intializing and is left running.
  // Implementation here calls Job:start() if job with ID exists.
  virtual int start(JobId jid);

  // Fetch a job using the string representation of an ID.
  // Probably no reason to override the implementation here.
  virtual int start(std::string sjid);

  // Kill a job.
  // Returns zero if the job was running on submission and
  // a request to kill was submitted.
  virtual int kill(JobId jid);

  // Fetch a job using the string representation of an ID.
  // Probably no reason to override the implementation here.
  virtual int kill(std::string sjid);

  // Remove a job and any associated data.
  // Returns 0 for success.
  virtual int remove(JobId jid) =0;

  // Fetch a job using the string representation of an ID.
  // Probably no reason to override the implementation here.
  virtual int remove(std::string sjid);

  // Lock the mutex for this object.
  // Returns  the same status as PThreadMutex.
  virtual int lock() const;
  virtual int unlock() const;

public:  // const functions

  // Is this a valid scheduler.
  virtual bool is_valid() const =0;

  // Is an application available?
  virtual bool has_application(const Application& app) const =0;

  // Is an application available and a task installed for that
  // application?
  // Returns false if the task build was not requested, has not
  // completed or failed.
  // Default returns false.
  virtual bool has_task(const Application& app,
                        const Task& tsk) const;

  // Return the ID of the job used to build at task.
  // Default returns invalid.
  virtual JobId task_job(const Application& app,
                        const Task& tsk) const;

  // Return the list of jobs ID's.
  // Return by value to make this thread safe.
  virtual JobIdList jobs() const =0;

  // Return if this scheduler has a job with the specified ID.
  // Implementation here searches the list returned by jobs().
  // Subclasses likely have a sorted map that provides a more
  // efficient search.
  virtual bool has_job(JobId jid) const;

  // Fetch a job.
  // Returns an invalid job if the ID is not known.
  // Reference may be updated as job is processed.
  // Copy is a snapshot of the base part of the job.
  virtual Job& job(JobId jid) const =0;

  // Fetch a job using the string representation of an ID.
  // Probably no reason to override the implementation here.
  virtual Job& job(std::string sjid) const;

  // Return the log for this scheduler.
  // Return by value to make this thread safe.
  virtual Text log() const =0;

  // Connection string for the repository where jobs are stored
  // during processing. Blank if there is no such repository.
  // Default returns blank.
  virtual std::string job_repository_connection() const;

  // Pointer to the job repository if valid.
  // Returns blank if undefined or invalid.
  // Default returns 0.
  virtual JobRepository* job_repository() const;

  // Display jobs.
  // maxprint = max number to print
  // skip = number to skip before printing remainder
  std::ostream&
  print_jobs(std::ostream& lhs,
             JobIdList::size_type maxprint =100,
             JobIdList::size_type skip =0) const;

  // Display jobs to standard out and appends end of line.
  std::ostream&
  print_jobs(JobIdList::size_type maxprint =100,
             JobIdList::size_type skip =0) const;

  // Job report.
  // Displays the number of jobs in each state.
  std::ostream& job_report(std::ostream& lhs) const;

  // Job report to standard out and appends end of line.
  std::ostream& job_report() const;

  // Output stream. Called by stream insertion operator.
  virtual std::ostream& ostr(std::ostream& str) const =0;

  // Write XML description of the full type.
  // This specifies the initial state of the scheduler.
  // Caller is resposible for managing the returned element.
  // Returns 0 for failure.
  virtual const XmlElement* xml() const =0;

  // Display.
  void display() const;

  // Fetch a report on the service resource usage.
  // Clients should override and report status of service.
  virtual std::string resource_report() const;

};

}  // end namespace dial

// Output stream
std::ostream&
operator<<(std::ostream& lhs, const dial::Scheduler& rhs);

#endif