root/gnuradio/trunk/gcell/src/lib/runtime/gc_job_manager.h

/* -*- c++ -*- */
/*
 * Copyright 2007,2008 Free Software Foundation, Inc.
 * 
 * This file is part of GNU Radio
 * 
 * GNU Radio is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3, or (at your option)
 * any later version.
 * 
 * GNU Radio is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License along
 * with this program; if not, write to the Free Software Foundation, Inc.,
 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 */

#ifndef INCLUDED_GC_JOB_MANAGER_H
#define INCLUDED_GC_JOB_MANAGER_H

#include <boost/utility.hpp>
#include <boost/shared_ptr.hpp>
#include <vector>
#include <string>
#include <stdexcept>
#include <libspe2.h>
#include "gc_job_desc.h"

class gc_job_manager;
typedef boost::shared_ptr<gc_job_manager> gc_job_manager_sptr;
typedef boost::shared_ptr<spe_program_handle_t> spe_program_handle_sptr;
typedef boost::shared_ptr<gc_job_desc> gc_job_desc_sptr;

/*!
 * \brief Return a boost::shared_ptr to an spe_program_handle_t
 *
 * \param filename is the name of the SPE ELF executable to open.
 *
 * Calls spe_image_open to open the file.  If successful returns a
 * boost::shared_ptr that will call spe_image_close when it's time to
 * free the object.
 *
 * Returns the equivalent of the NULL pointer if the file cannot be
 * opened, or if it's not an SPE ELF object file.
 *
 * \sa gc_program_handle_from_address
 */
spe_program_handle_sptr 
gc_program_handle_from_filename(const std::string &filename);

/*!
 * \brief Return a boost::shared_ptr to an spe_program_handle_t
 *
 * \param handle is a non-zero pointer to an embedded SPE image.
 *
 * If successful returns a boost::shared_ptr that does nothing when
 * it's time to free the object.
 *
 * \sa gc_program_handle_from_filename
 */
spe_program_handle_sptr 
gc_program_handle_from_address(spe_program_handle_t *handle);

/*!
 * \brief map gc_job_status_t into a string
 */
const std::string
gc_job_status_string(gc_job_status_t status);

/*
 * \brief Options that configure the job_manager.
 * The default values are reasonable.
 */
struct gc_jm_options {
  unsigned int max_jobs;            // max # of job descriptors in system
  unsigned int max_client_threads;  // max # of client threads of job manager
  unsigned int nspes;               // how many SPEs shall we use? 0 -> all of them
  bool gang_schedule;               // shall we gang schedule?
  bool use_affinity;                // shall we try for affinity (FIXME not implmented)
  bool enable_logging;              // shall we log SPE events?
  uint32_t log2_nlog_entries;              // log2 of number of log entries (default is 12 == 4k)
  spe_program_handle_sptr program_handle;  // program to load into SPEs

  gc_jm_options() :
    max_jobs(0), max_client_threads(0), nspes(0),
    gang_schedule(false), use_affinity(false),
    enable_logging(false), log2_nlog_entries(12)
  {
  }

  gc_jm_options(spe_program_handle_sptr program_handle_,
                unsigned int nspes_ = 0) :
    max_jobs(0), max_client_threads(0), nspes(nspes_),
    gang_schedule(false), use_affinity(false),
    enable_logging(false), log2_nlog_entries(12),
    program_handle(program_handle_)
  {
  }
};

enum gc_wait_mode {
  GC_WAIT_ANY,
  GC_WAIT_ALL,
};

/*
 * exception classes
 */
class gc_exception : public std::runtime_error
{
public:
  gc_exception(const std::string &msg);
};

class gc_unknown_proc : public gc_exception
{
public:
  gc_unknown_proc(const std::string &msg);
};

class gc_bad_alloc : public gc_exception
{
public:
  gc_bad_alloc(const std::string &msg);
};

class gc_bad_align : public gc_exception
{
public:
  gc_bad_align(const std::string &msg);
};

class gc_bad_submit : public gc_exception
{
public:
  gc_bad_submit(const std::string &name, gc_job_status_t status);
};

/*
 * \brief Create an instance of the job manager
 */
gc_job_manager_sptr
gc_make_job_manager(const gc_jm_options *options = 0);


/*!
 * \brief Abstract class that manages SPE jobs.
 *
 * There is typically a single instance derived from this class.
 * It is safe to call its methods from any thread.
 */
class gc_job_manager : boost::noncopyable
{
public:
  gc_job_manager(const gc_jm_options *options = 0); 

  virtual ~gc_job_manager();

  /*!
   * Stop accepting new jobs.  Wait for existing jobs to complete.
   * Return all managed SPE's to the system.
   */
  virtual bool shutdown() = 0;

  /*!
   * \brief Return number of SPE's currently allocated to job manager.
   */
  virtual int nspes() const = 0;

  /*!
   * \brief Return a pointer to a properly aligned job descriptor,
   * or throws gc_bad_alloc if there are none available.
   */
  virtual gc_job_desc *alloc_job_desc() = 0;

  /*
   *! Free a job descriptor previously allocated with alloc_job_desc()
   *
   * \param[in] jd pointer to job descriptor to free.
   */
  virtual void free_job_desc(gc_job_desc *jd) = 0;

  /*!
   * \brief Submit a job for asynchronous processing on an SPE.
   *
   * \param[in] jd pointer to job description
   *
   * The caller must not read or write the job description
   * or any of the memory associated with any indirect arguments
   * until after calling wait_job.
   *
   * \returns true iff the job was successfully enqueued.
   * If submit_job returns false, check jd->status for additional info.
   */
  virtual bool submit_job(gc_job_desc *jd) = 0;

  /*!
   * \brief Wait for job to complete.
   *
   * A thread may only wait for jobs which it submitted.
   *
   * \returns true if sucessful, else false.
   */
  virtual bool 
  wait_job(gc_job_desc *jd) = 0;

  /*!
   * \brief wait for 1 or more jobs to complete.
   *
   * \param[input] njobs is the length of arrays \p jd and \p done.
   * \param[input] jd are the jobs that are to be waited for.
   * \param[output] done indicates whether the corresponding job is complete.
   * \param[input] mode indicates whether to wait for ALL or ANY of the jobs
   *   in \p jd to complete.
   *
   * A thread may only wait for jobs which it submitted.
   *
   * \returns number of jobs completed, or -1 if error.
   * The caller must examine the status field of each job to confirm
   * successful completion of the job.
   */
  virtual int
  wait_jobs(unsigned int njobs,
            gc_job_desc *jd[], bool done[], gc_wait_mode mode) = 0;

  /*!
   * Return the maximum number of bytes of EA arguments that may be
   * copied to or from the SPE in a single job.  The limit applies
   * independently to the "get" and "put" args.  
   * \sa gc_job_desc_t, gc_job_ea_args_t
   */
  virtual int ea_args_maxsize() = 0;

  /*!
   * Return gc_proc_id_t associated with spu procedure \p proc_name if one
   * exists, otherwise throws gc_unknown_proc.
   */
  virtual gc_proc_id_t lookup_proc(const std::string &proc_name) = 0;
  
  /*!
   * Return a vector of all known spu procedure names.
   */
  virtual std::vector<std::string> proc_names() = 0;

  virtual void set_debug(int debug);
  virtual int debug();

  /* ----- static methods ----- */

  /*!
   * \brief Set the singleton gc_job_manager instance.
   * \param mgr is the job manager instance.
   *
   * The singleton is weakly held, thus the caller must maintain
   * a reference to the mgr for the duration.  (If we held the
   * manager strongly, the destructor would never be called, and the
   * resources (SPEs) would not be returned.)  Bottom line: the
   * caller is responsible for life-time management.
   */
  static void set_singleton(gc_job_manager_sptr mgr);

  /*!
   * \brief Retrieve the singleton gc_job_manager instance.
   *
   * Returns the singleton gc_job_manager instance or raises
   * boost::bad_weak_ptr if the singleton is empty.
   */
  static gc_job_manager_sptr singleton();

  /*!
   * \brief return a boost::shared_ptr to a job descriptor.
   */
  static gc_job_desc_sptr make_jd_sptr(gc_job_manager_sptr mgr, gc_job_desc *jd);

  /*!
   * \brief allocate a job descriptor and return a boost::shared_ptr to it.
   */
  static gc_job_desc_sptr alloc_job_desc(gc_job_manager_sptr mgr);
};


#endif /* INCLUDED_GC_JOB_MANAGER_H */