git.gag.com Git - debian/gnuradio/blob - gcell/src/lib/runtime/gc_job_manager.h

   1 /* -*- c++ -*- */
   2 /*
   3  * Copyright 2007,2008 Free Software Foundation, Inc.
   4  *
   5  * This file is part of GNU Radio
   6  *
   7  * GNU Radio is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; either version 3, or (at your option)
  10  * any later version.
  11  *
  12  * GNU Radio is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15  * GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License along
  18  * with this program; if not, write to the Free Software Foundation, Inc.,
  19  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
  20  */
  21
  22 #ifndef INCLUDED_GC_JOB_MANAGER_H
  23 #define INCLUDED_GC_JOB_MANAGER_H
  24
  25 #include <boost/utility.hpp>
  26 #include <boost/shared_ptr.hpp>
  27 #include <vector>
  28 #include <string>
  29 #include <stdexcept>
  30 #include <libspe2.h>
  31 #include "gc_job_desc.h"
  32
  33 class gc_job_manager;
  34 typedef boost::shared_ptr<gc_job_manager> gc_job_manager_sptr;
  35 typedef boost::shared_ptr<spe_program_handle_t> spe_program_handle_sptr;
  36
  37 /*!
  38  * \brief Return a boost::shared_ptr to an spe_program_handle_t
  39  *
  40  * \param filename is the name of the SPE ELF executable to open.
  41  *
  42  * Calls spe_image_open to open the file.  If successful returns a
  43  * boost::shared_ptr that will call spe_image_close when it's time to
  44  * free the object.
  45  *
  46  * Returns the equivalent of the NULL pointer if the file cannot be
  47  * opened, or if it's not an SPE ELF object file.
  48  *
  49  * \sa gc_program_handle_from_address
  50  */
  51 spe_program_handle_sptr
  52 gc_program_handle_from_filename(const std::string &filename);
  53
  54 /*!
  55  * \brief Return a boost::shared_ptr to an spe_program_handle_t
  56  *
  57  * \param handle is a non-zero pointer to an embedded SPE image.
  58  *
  59  * If successful returns a boost::shared_ptr that does nothing when
  60  * it's time to free the object.
  61  *
  62  * \sa gc_program_handle_from_filename
  63  */
  64 spe_program_handle_sptr
  65 gc_program_handle_from_address(spe_program_handle_t *handle);
  66
  67 /*!
  68  * \brief map gc_job_status_t into a string
  69  */
  70 const std::string
  71 gc_job_status_string(gc_job_status_t status);
  72
  73 /*
  74  * \brief Options that configure the job_manager.
  75  * The default values are reasonable.
  76  */
  77 struct gc_jm_options {
  78   unsigned int max_jobs;            // max # of job descriptors in system
  79   unsigned int max_client_threads;  // max # of client threads of job manager
  80   unsigned int nspes;               // how many SPEs shall we use? 0 -> all of them
  81   bool gang_schedule;               // shall we gang schedule?
  82   bool use_affinity;                // shall we try for affinity (FIXME not implmented)
  83   bool enable_logging;              // shall we log SPE events?
  84   uint32_t log2_nlog_entries;              // log2 of number of log entries (default is 12 == 4k)
  85   spe_program_handle_sptr program_handle;  // program to load into SPEs
  86
  87   gc_jm_options() :
  88     max_jobs(0), max_client_threads(0), nspes(0),
  89     gang_schedule(true), use_affinity(false),
  90     enable_logging(false), log2_nlog_entries(12)
  91   {
  92   }
  93 };
  94
  95 enum gc_wait_mode {
  96   GC_WAIT_ANY,
  97   GC_WAIT_ALL,
  98 };
  99
 100 /*
 101  * exception classes
 102  */
 103 class gc_exception : public std::runtime_error
 104 {
 105 public:
 106   gc_exception(const std::string &msg);
 107 };
 108
 109 class gc_unknown_proc : public gc_exception
 110 {
 111 public:
 112   gc_unknown_proc(const std::string &msg);
 113 };
 114
 115 class gc_bad_alloc : public gc_exception
 116 {
 117 public:
 118   gc_bad_alloc(const std::string &msg);
 119 };
 120
 121 class gc_bad_align : public gc_exception
 122 {
 123 public:
 124   gc_bad_align(const std::string &msg);
 125 };
 126
 127 class gc_bad_submit : public gc_exception
 128 {
 129 public:
 130   gc_bad_submit(const std::string &name, gc_job_status_t status);
 131 };
 132
 133 /*
 134  * \brief Create an instance of the job manager
 135  */
 136 gc_job_manager_sptr
 137 gc_make_job_manager(const gc_jm_options *options = 0);
 138
 139
 140 /*!
 141  * \brief Abstract class that manages SPE jobs.
 142  *
 143  * There is typically a single instance derived from this class.
 144  * It is safe to call its methods from any thread.
 145  */
 146 class gc_job_manager : boost::noncopyable
 147 {
 148 public:
 149   gc_job_manager(const gc_jm_options *options = 0);
 150
 151   virtual ~gc_job_manager();
 152
 153   /*!
 154    * Stop accepting new jobs.  Wait for existing jobs to complete.
 155    * Return all managed SPE's to the system.
 156    */
 157   virtual bool shutdown() = 0;
 158
 159   /*!
 160    * \brief Return number of SPE's currently allocated to job manager.
 161    */
 162   virtual int nspes() const = 0;
 163
 164   /*!
 165    * \brief Return a pointer to a properly aligned job descriptor,
 166    * or throws gc_bad_alloc if there are none available.
 167    */
 168   virtual gc_job_desc *alloc_job_desc() = 0;
 169
 170   /*
 171    *! Free a job descriptor previously allocated with alloc_job_desc()
 172    *
 173    * \param[in] jd pointer to job descriptor to free.
 174    */
 175   virtual void free_job_desc(gc_job_desc *jd) = 0;
 176
 177   /*!
 178    * \brief Submit a job for asynchronous processing on an SPE.
 179    *
 180    * \param[in] jd pointer to job description
 181    *
 182    * The caller must not read or write the job description
 183    * or any of the memory associated with any indirect arguments
 184    * until after calling wait_job.
 185    *
 186    * \returns true iff the job was successfully enqueued.
 187    * If submit_job returns false, check jd->status for additional info.
 188    */
 189   virtual bool submit_job(gc_job_desc *jd) = 0;
 190
 191   /*!
 192    * \brief Wait for job to complete.
 193    *
 194    * A thread may only wait for jobs which it submitted.
 195    *
 196    * \returns true if sucessful, else false.
 197    */
 198   virtual bool
 199   wait_job(gc_job_desc *jd) = 0;
 200
 201   /*!
 202    * \brief wait for 1 or more jobs to complete.
 203    *
 204    * \param[input] njobs is the length of arrays \p jd and \p done.
 205    * \param[input] jd are the jobs that are to be waited for.
 206    * \param[output] done indicates whether the corresponding job is complete.
 207    * \param[input] mode indicates whether to wait for ALL or ANY of the jobs
 208    *   in \p jd to complete.
 209    *
 210    * A thread may only wait for jobs which it submitted.
 211    *
 212    * \returns number of jobs completed, or -1 if error.
 213    * The caller must examine the status field of each job to confirm
 214    * successful completion of the job.
 215    */
 216   virtual int
 217   wait_jobs(unsigned int njobs,
 218             gc_job_desc *jd[], bool done[], gc_wait_mode mode) = 0;
 219
 220   /*!
 221    * Return the maximum number of bytes of EA arguments that may be
 222    * copied to or from the SPE in a single job.  The limit applies
 223    * independently to the "get" and "put" args.
 224    * \sa gc_job_desc_t, gc_job_ea_args_t
 225    */
 226   virtual int ea_args_maxsize() = 0;
 227
 228   /*!
 229    * Return gc_proc_id_t associated with spu procedure \p proc_name if one
 230    * exists, otherwise throws gc_unknown_proc.
 231    */
 232   virtual gc_proc_id_t lookup_proc(const std::string &proc_name) = 0;
 233
 234   /*!
 235    * Return a vector of all known spu procedure names.
 236    */
 237   virtual std::vector<std::string> proc_names() = 0;
 238
 239   /*!
 240    * \brief Set the singleton gc_job_manager instance.
 241    * \param mgr is the job manager instance.
 242    *
 243    * The singleton is weakly held, thus the caller must maintain
 244    * a reference to the mgr for the duration.  (If we held the
 245    * manager strongly, the destructor would never be called, and the
 246    * resources (SPEs) would not be returned.)  Bottom line: the
 247    * caller is responsible for life-time management.
 248    */
 249   static void set_singleton(gc_job_manager_sptr mgr);
 250
 251   /*!
 252    * \brief Retrieve the singleton gc_job_manager instance.
 253    *
 254    * Returns the singleton gc_job_manager instance or raises
 255    * boost::bad_weak_ptr if the singleton is empty.
 256    */
 257   static gc_job_manager_sptr singleton();
 258
 259
 260   virtual void set_debug(int debug);
 261   virtual int debug();
 262 };
 263
 264
 265 #endif /* INCLUDED_GC_JOB_MANAGER_H */