3 * Copyright 2007,2008 Free Software Foundation, Inc.
5 * This file is part of GNU Radio
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)
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.
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.
22 #ifndef INCLUDED_GC_JOB_MANAGER_H
23 #define INCLUDED_GC_JOB_MANAGER_H
25 #include <boost/utility.hpp>
26 #include <boost/shared_ptr.hpp>
31 #include "gc_job_desc.h"
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 typedef boost::shared_ptr<gc_job_desc> gc_job_desc_sptr;
39 * \brief Return a boost::shared_ptr to an spe_program_handle_t
41 * \param filename is the name of the SPE ELF executable to open.
43 * Calls spe_image_open to open the file. If successful returns a
44 * boost::shared_ptr that will call spe_image_close when it's time to
47 * Returns the equivalent of the NULL pointer if the file cannot be
48 * opened, or if it's not an SPE ELF object file.
50 * \sa gc_program_handle_from_address
52 spe_program_handle_sptr
53 gc_program_handle_from_filename(const std::string &filename);
56 * \brief Return a boost::shared_ptr to an spe_program_handle_t
58 * \param handle is a non-zero pointer to an embedded SPE image.
60 * If successful returns a boost::shared_ptr that does nothing when
61 * it's time to free the object.
63 * \sa gc_program_handle_from_filename
65 spe_program_handle_sptr
66 gc_program_handle_from_address(spe_program_handle_t *handle);
69 * \brief map gc_job_status_t into a string
72 gc_job_status_string(gc_job_status_t status);
75 * \brief Options that configure the job_manager.
76 * The default values are reasonable.
78 struct gc_jm_options {
79 unsigned int max_jobs; // max # of job descriptors in system
80 unsigned int max_client_threads; // max # of client threads of job manager
81 unsigned int nspes; // how many SPEs shall we use? 0 -> all of them
82 bool gang_schedule; // shall we gang schedule?
83 bool use_affinity; // shall we try for affinity (FIXME not implmented)
84 bool enable_logging; // shall we log SPE events?
85 uint32_t log2_nlog_entries; // log2 of number of log entries (default is 12 == 4k)
86 spe_program_handle_sptr program_handle; // program to load into SPEs
89 max_jobs(0), max_client_threads(0), nspes(0),
90 gang_schedule(false), use_affinity(false),
91 enable_logging(false), log2_nlog_entries(12)
95 gc_jm_options(spe_program_handle_sptr program_handle_,
96 unsigned int nspes_ = 0) :
97 max_jobs(0), max_client_threads(0), nspes(nspes_),
98 gang_schedule(false), use_affinity(false),
99 enable_logging(false), log2_nlog_entries(12),
100 program_handle(program_handle_)
113 class gc_exception : public std::runtime_error
116 gc_exception(const std::string &msg);
119 class gc_unknown_proc : public gc_exception
122 gc_unknown_proc(const std::string &msg);
125 class gc_bad_alloc : public gc_exception
128 gc_bad_alloc(const std::string &msg);
131 class gc_bad_align : public gc_exception
134 gc_bad_align(const std::string &msg);
137 class gc_bad_submit : public gc_exception
140 gc_bad_submit(const std::string &name, gc_job_status_t status);
144 * \brief Create an instance of the job manager
147 gc_make_job_manager(const gc_jm_options *options = 0);
151 * \brief Abstract class that manages SPE jobs.
154 * There is typically a single instance derived from this class.
155 * It is safe to call its methods from any thread.
157 class gc_job_manager : boost::noncopyable
160 gc_job_manager(const gc_jm_options *options = 0);
162 virtual ~gc_job_manager();
165 * Stop accepting new jobs. Wait for existing jobs to complete.
166 * Return all managed SPE's to the system.
168 virtual bool shutdown() = 0;
171 * \brief Return number of SPE's currently allocated to job manager.
173 virtual int nspes() const = 0;
176 * \brief Return a pointer to a properly aligned job descriptor,
177 * or throws gc_bad_alloc if there are none available.
179 virtual gc_job_desc *alloc_job_desc() = 0;
182 *! Free a job descriptor previously allocated with alloc_job_desc()
184 * \param[in] jd pointer to job descriptor to free.
186 virtual void free_job_desc(gc_job_desc *jd) = 0;
189 * \brief Submit a job for asynchronous processing on an SPE.
191 * \param[in] jd pointer to job description
193 * The caller must not read or write the job description
194 * or any of the memory associated with any indirect arguments
195 * until after calling wait_job.
197 * \returns true iff the job was successfully enqueued.
198 * If submit_job returns false, check jd->status for additional info.
200 virtual bool submit_job(gc_job_desc *jd) = 0;
203 * \brief Wait for job to complete.
205 * A thread may only wait for jobs which it submitted.
207 * \returns true if sucessful, else false.
210 wait_job(gc_job_desc *jd) = 0;
213 * \brief wait for 1 or more jobs to complete.
215 * \param[in] njobs is the length of arrays \p jd and \p done.
216 * \param[in] jd are the jobs that are to be waited for.
217 * \param[out] done indicates whether the corresponding job is complete.
218 * \param[in] mode indicates whether to wait for ALL or ANY of the jobs
219 * in \p jd to complete.
221 * A thread may only wait for jobs which it submitted.
223 * \returns number of jobs completed, or -1 if error.
224 * The caller must examine the status field of each job to confirm
225 * successful completion of the job.
228 wait_jobs(unsigned int njobs,
229 gc_job_desc *jd[], bool done[], gc_wait_mode mode) = 0;
232 * Return the maximum number of bytes of EA arguments that may be
233 * copied to or from the SPE in a single job. The limit applies
234 * independently to the "get" and "put" args.
235 * \sa gc_job_desc_t, gc_job_ea_args_t
237 virtual int ea_args_maxsize() = 0;
240 * Return gc_proc_id_t associated with spu procedure \p proc_name if one
241 * exists, otherwise throws gc_unknown_proc.
243 virtual gc_proc_id_t lookup_proc(const std::string &proc_name) = 0;
246 * Return a vector of all known spu procedure names.
248 virtual std::vector<std::string> proc_names() = 0;
250 virtual void set_debug(int debug);
253 /* ----- static methods ----- */
256 * \brief Set the singleton gc_job_manager instance.
257 * \param mgr is the job manager instance.
259 * The singleton is weakly held, thus the caller must maintain
260 * a reference to the mgr for the duration. (If we held the
261 * manager strongly, the destructor would never be called, and the
262 * resources (SPEs) would not be returned.) Bottom line: the
263 * caller is responsible for life-time management.
265 static void set_singleton(gc_job_manager_sptr mgr);
268 * \brief Retrieve the singleton gc_job_manager instance.
270 * Returns the singleton gc_job_manager instance or raises
271 * boost::bad_weak_ptr if the singleton is empty.
273 static gc_job_manager_sptr singleton();
276 * \brief return a boost::shared_ptr to a job descriptor.
278 static gc_job_desc_sptr make_jd_sptr(gc_job_manager_sptr mgr, gc_job_desc *jd);
281 * \brief allocate a job descriptor and return a boost::shared_ptr to it.
283 static gc_job_desc_sptr alloc_job_desc(gc_job_manager_sptr mgr);
287 #endif /* INCLUDED_GC_JOB_MANAGER_H */