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 <vector>
  27 #include <string>
  28 #include <libspe2.h>
  29 #include "gc_job_desc.h"
  30
  31 class gc_job_manager;
  32
  33 enum gc_wait_mode {
  34   GC_WAIT_ANY,
  35   GC_WAIT_ALL,
  36 };
  37
  38 /*
  39  * \brief Options that configure the job_manager.
  40  * The default values are reasonable.
  41  */
  42 struct gc_jm_options {
  43   unsigned int max_jobs;            // max # of job descriptors in system
  44   unsigned int max_client_threads;  // max # of client threads of job manager
  45   unsigned int nspes;               // how many SPEs shall we use? 0 -> all of them
  46   bool gang_schedule;               // shall we gang schedule?
  47   bool use_affinity;                // shall we try for affinity (FIXME not implmented)
  48   bool enable_logging;              // shall we log SPE events?
  49   uint32_t log2_nlog_entries;            // log2 of number of log entries (default is 12 == 4k)
  50   spe_program_handle_t *program_handle;  // program to load into SPEs
  51
  52   gc_jm_options() :
  53     max_jobs(0), max_client_threads(0), nspes(0),
  54     gang_schedule(true), use_affinity(false),
  55     enable_logging(false), log2_nlog_entries(12),
  56     program_handle(0)
  57   {
  58   }
  59 };
  60
  61
  62 /*
  63  * \brief Create an instance of the job manager
  64  */
  65 gc_job_manager *
  66 gc_make_job_manager(const gc_jm_options *options = 0);
  67
  68
  69 /*!
  70  * \brief Abstract class that manages SPE jobs.
  71  *
  72  * There is typically a single instance derived from this class.
  73  * It is safe to call its methods from any thread.
  74  */
  75 class gc_job_manager : boost::noncopyable
  76 {
  77 public:
  78   gc_job_manager(const gc_jm_options *options = 0);
  79
  80   virtual ~gc_job_manager();
  81
  82   /*!
  83    * Stop accepting new jobs.  Wait for existing jobs to complete.
  84    * Return all managed SPE's to the system.
  85    */
  86   virtual bool shutdown() = 0;
  87
  88   /*!
  89    * \brief Return number of SPE's currently allocated to job manager.
  90    */
  91   virtual int nspes() const = 0;
  92
  93   /*!
  94    * \brief Return a pointer to a properly aligned job descriptor,
  95    * or zero if none are available.
  96    */
  97   virtual gc_job_desc *alloc_job_desc() = 0;
  98
  99   /*
 100    *! Free a job descriptor previously allocated with alloc_job_desc()
 101    *
 102    * \param[in] jd pointer to job descriptor to free.
 103    */
 104   virtual void free_job_desc(gc_job_desc *jd) = 0;
 105
 106   /*!
 107    * \brief Submit a job for asynchronous processing on an SPE.
 108    *
 109    * \param[in] jd pointer to job description
 110    *
 111    * The caller must not read or write the job description
 112    * or any of the memory associated with any indirect arguments
 113    * until after calling wait_job.
 114    *
 115    * \returns true iff the job was successfully enqueued.
 116    * If submit_job returns false, check jd->status for additional info.
 117    */
 118   virtual bool submit_job(gc_job_desc *jd) = 0;
 119
 120   /*!
 121    * \brief Wait for job to complete.
 122    *
 123    * A thread may only wait for jobs which it submitted.
 124    *
 125    * \returns true if sucessful, else false.
 126    */
 127   virtual bool
 128   wait_job(gc_job_desc *jd) = 0;
 129
 130   /*!
 131    * \brief wait for 1 or more jobs to complete.
 132    *
 133    * \param[input] njobs is the length of arrays \p jd and \p done.
 134    * \param[input] jd are the jobs that are to be waited for.
 135    * \param[output] done indicates whether the corresponding job is complete.
 136    * \param[input] mode indicates whether to wait for ALL or ANY of the jobs
 137    *   in \p jd to complete.
 138    *
 139    * A thread may only wait for jobs which it submitted.
 140    *
 141    * \returns number of jobs completed, or -1 if error.
 142    */
 143   virtual int
 144   wait_jobs(unsigned int njobs,
 145             gc_job_desc *jd[], bool done[], gc_wait_mode mode) = 0;
 146
 147   /*!
 148    * Return the maximum number of bytes of EA arguments that may be
 149    * copied to or from the SPE in a single job.  The limit applies
 150    * independently to the "get" and "put" args.
 151    * \sa gc_job_desc_t, gc_job_ea_args_t
 152    */
 153   virtual int ea_args_maxsize() = 0;
 154
 155   /*!
 156    * Return gc_proc_id_t associated with spu procedure \p proc_name if one
 157    * exists, otherwise return GCP_UNKNOWN_PROC.
 158    */
 159   virtual gc_proc_id_t lookup_proc(const std::string &proc_name) = 0;
 160
 161   /*!
 162    * Return a vector of all known spu procedure names.
 163    */
 164   virtual std::vector<std::string> proc_names() = 0;
 165
 166   virtual void set_debug(int debug);
 167   virtual int debug();
 168 };
 169
 170
 171 #endif /* INCLUDED_GC_JOB_MANAGER_H */