source: branches/2.0/drmaa2_utils/drmaa_utils/jsession.h @ 81

Revision 81, 8.3 KB checked in by mmamonski, 12 years ago (diff)

DRMAA 2.0 for PBS compiles
Line 
1/* $Id: session.h 13 2011-04-20 15:41:43Z mmamonski $ */
2/*
3 *  PSNC DRMAA 2.0 utilities library
4 *  Copyright (C) 2012  Poznan Supercomputing and Networking Center
5 *
6 *  This program is free software: you can redistribute it and/or modify
7 *  it under the terms of the GNU General Public License as published by
8 *  the Free Software Foundation, either version 3 of the License, or
9 *  (at your option) any later version.
10 *
11 *  This program is distributed in the hope that it will be useful,
12 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
13 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
14 *  GNU General Public License for more details.
15 *
16 *  You should have received a copy of the GNU General Public License
17 *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
18 */
19
20/**
21 * @file session.h
22 * DRMAA session.
23 */
24
25#ifndef __DRMAA_UTILS__SESSION_H
26#define __DRMAA_UTILS__SESSION_H
27
28#include <sys/time.h>
29
30#include <drmaa_utils/common.h>
31#include <drmaa_utils/thread.h>
32
33/** Creates new DRMAA session. */
34fsd_drmaa_jsession_t *
35fsd_drmaa_jsession_new( const char *contact );
36
37/**
38 * Get current (global) DRMAA session
39 * and increase it's reference count.
40 */
41fsd_drmaa_jsession_t *
42fsd_drmaa_jsession_get(void);
43
44/**
45 * An action to be taken when job is missing from queue.
46 */
47typedef enum {
48        /**
49         * Always raise #FSD_ERRNO_INTERNAL_ERROR (one per job)
50         * in drmaa_wait() or drmaa_synchronize()
51         * when job disappearance is spotted.
52         */
53        FSD_REVEAL_MISSING_JOBS,
54        /**
55         * Treat missing jobs as terminated with status
56         * depending on last known state and action (drmaa_control()).
57         */
58        FSD_IGNORE_MISSING_JOBS,
59        /**
60         * Treat missing jobs as terminated
61         * but only before they enter into running state.
62         */
63        FSD_IGNORE_QUEUED_MISSING_JOBS
64} fsd_missing_jobs_behaviour_t;
65
66
67/** DRMAA JobSession data. */
68struct fsd_drmaa_jsession_s {
69        drmaa2_string (*get_contact)(fsd_drmaa_jsession_t *self);
70
71        drmaa2_string (*get_session_name)(fsd_drmaa_jsession_t *self);
72
73        drmaa2_string_list (*get_job_categories)(fsd_drmaa_jsession_t *self);
74
75        drmaa2_j_list (*get_jobs)(fsd_drmaa_jsession_t *self);
76
77        drmaa2_jarray (*get_job_array)(fsd_drmaa_jsession_t *self);
78
79        drmaa2_j (*run_job)(fsd_drmaa_jsession_t *self);
80
81        drmaa2_jarray (*run_bulk_jobs)(fsd_drmaa_jsession_t *self);
82
83        drmaa2_j (*wait_any_started)(fsd_drmaa_jsession_t *self, const drmaa2_j_list l, const time_t timeout);
84
85        drmaa2_j (*wait_any_terminated)(fsd_drmaa_jsession_t *self, const drmaa2_j_list l, const time_t timeout);
86
87
88        void (*destroy)(fsd_drmaa_jsession_t *self);
89
90        void (*close)(fsd_drmaa_jsession_t *self);
91
92        drmaa2_string contact;
93        drmaa2_string session_name;
94
95#if 0
96
97        /**
98         * Destroy session without waiting for releasing references.
99         */
100        void (*
101        destroy_nowait)( fsd_drmaa_jsession_t *self );
102
103
104        /** Implements drmaa_run_job(). */
105        char* (*
106        run_job)(
107                        fsd_drmaa_jsession_t *self,
108                        const fsd_template_t *jt
109                        );
110
111        /** Implements drmaa_run_bulk_jobs(). */
112        fsd_iter_t* (*
113        run_bulk)(
114                        fsd_drmaa_jsession_t *self,
115                        const fsd_template_t *jt,
116                        int start, int end, int incr
117                        );
118
119        /** Implements drmaa_control(). */
120        void (*
121        control_job)(
122                        fsd_drmaa_jsession_t *self,
123                        const char *job_id, int action
124                        );
125
126        /** Implements drmaa_job_ps(). */
127        void (*
128        job_ps)(
129                        fsd_drmaa_jsession_t *self,
130                        const char *job_id, int *remote_ps
131                        );
132
133        /** Implements drmaa_synchronize(). */
134        void (*
135        synchronize)(
136                        fsd_drmaa_jsession_t *self,
137                        const char **input_job_ids, const struct timespec *timeout,
138                        bool dispose
139                        );
140
141        /**
142         * Implements drmaa_wait() call.
143         * @param self     DRMAA session.
144         * @param job_id   Job identifer to wait for or #DRMAA_JOB_IDS_SESSION_ANY
145         * @param timeout  Timeout after which call shall raise
146         *   #FSD_DRMAA_ERRNO_EXIT_TIMEOUT if job not terminated or \c NULL.
147         * @param status   Terminated job status (output only).
148         * @param rusage   Job resource usage (output only).
149         * @see drmaa_wait()
150         * @see #wait_for_single_job  #wait_for_any_job
151         */
152        char* (*
153        wait)(
154                        fsd_drmaa_jsession_t *self,
155                        const char *job_id, const struct timespec *timeout,
156                        int *status, fsd_iter_t **rusage
157                        );
158
159        /**
160         * Construct new job object.
161         * @return Reference to newly created job.
162         */
163        fsd_job_t* (*
164        new_job)( fsd_drmaa_jsession_t *self, const char *job_id );
165
166        char* (*
167        run_impl)(
168                        fsd_drmaa_jsession_t *self,
169                        const fsd_template_t *jt, int bulk_incr
170                        );
171
172        /**
173         * Wait until given job terminates (either successfuly or not).
174         * @param self     DRMAA session.
175         * @param job_id   Identifier of job to wait for.
176         * @param timeout  If not \c NULL and job does not terminate
177         *   in given amount of time function returns and
178         *   #FSD_DRMAA_ERRNO_EXIT_TIMEOUT is raised.
179         * @param status   If not \c NULL job status code is stored here.
180         * @param rusage   If not \c NULL list of used resources is returned.
181         * @param dispose  If \c true job information is removed from session
182         *   at the end of call and further accesses to this job_id will
183         *   raise #FSD_DRMAA_ERRNO_INVALID_JOB.  Otherwise job data is held.
184         * @see #wait_for_any_job #wait
185         */
186        void (*
187        wait_for_single_job)(
188                        fsd_drmaa_jsession_t *self,
189                        const char *job_id, const struct timespec *timeout,
190                        int *status, fsd_iter_t **rusage, bool dispose
191                        );
192
193        /**
194         * Wait until and job left in session terminates.
195         * @return  Identifier of waited job.
196         *   Freeing responsobility is left to the callee.
197         * @see #wait_for_single_job #wait
198         */
199        char* (*
200        wait_for_any_job)(
201                        fsd_drmaa_jsession_t *self,
202                        const struct timespec *timeout,
203                        int *status, fsd_iter_t **rusage,
204                        bool dispose
205                        );
206
207        void (*
208        wait_for_job_status_change)(
209                        fsd_drmaa_jsession_t *self,
210                        fsd_cond_t *wait_condition,
211                        fsd_mutex_t *mutex,
212                        const struct timespec *timeout
213                        );
214
215        void* (*
216        wait_thread)( fsd_drmaa_jsession_t *self );
217
218        void (*
219        stop_wait_thread)( fsd_drmaa_jsession_t *self );
220
221        /**
222         * Make status of all jobs held in session up to date.
223         */
224        void (*
225        update_all_jobs_status)( fsd_drmaa_jsession_t *self );
226
227        /** Return list of all jobs within session. */
228        char** (*
229        get_submited_job_ids)(
230                        fsd_drmaa_jsession_t *self
231                        );
232
233        /**
234         * Get job with given identifier.
235         * @return New reference to job or \c NULL
236         *   if no job found.
237         */
238        fsd_job_t* (*
239        get_job)(
240                        fsd_drmaa_jsession_t *self, const char *job_id
241                        );
242
243        /**
244         * Tries to load configuration from following locations in order
245         * (configuration settings from later locations override
246         * those from earlier):
247         * /etc/basename.conf, ~/.basename.conf, $basename_CONF.
248         */
249        void (*
250        load_configuration)(
251                        fsd_drmaa_jsession_t *self, const char *basename
252                        );
253
254        void (*
255        read_configuration)(
256                        fsd_drmaa_jsession_t *self,
257                        const char *filename, bool must_exist,
258                        const char *configuration, size_t config_len
259                        );
260
261        void (*
262        apply_configuration)(
263                        fsd_drmaa_jsession_t *self
264                        );
265
266        /** Reference counter. */
267        int ref_cnt;
268
269        /**
270         * Whether #destroy was called and waits for releasing
271         * references.  If set pending #wait calls shall
272         * return with #FSD_DRMAA_ERRNO_NO_ACTIVE_SESSION error.
273         */
274        bool destroy_requested;
275
276
277
278        /**
279         * Jobs submitted within this DRMAA session
280         * and not disposed yet.
281         */
282        fsd_job_set_t *jobs;
283
284        /** DRMAA configuration. */
285        fsd_conf_dict_t *configuration;
286
287        /** Queue pooling delay (time delta). */
288        struct timespec pool_delay;
289
290        /**
291         * Cache job state for number of seconds.
292         * If positive drmaa_job_ps() returns remembered state without
293         * communicating with DRM for \a cache_job_state seconds since last
294         * update.
295         */
296        int cache_job_state;
297
298        /** Whether to wait for jobs in separate thread. */
299        bool enable_wait_thread;
300
301        /**
302         * Configuration dictionary which maps
303         * job categories to native specification.
304         */
305        fsd_conf_dict_t *job_categories;
306
307        /**
308         * How to behave when submitted job disappears from DRM queue.
309         */
310        fsd_missing_jobs_behaviour_t missing_jobs;
311
312        fsd_mutex_t mutex; /**< Mutex for accessing session data. */
313        fsd_cond_t wait_condition;  /**< Conditional for drmaa_wait() */
314        fsd_cond_t destroy_condition;  /**< Conditional for ref_cnt==1 */
315
316        /**
317         * Mutex for accessing connection to DRM.
318         *
319         * To prevent deadlocks #mutex should be acquired first
320         * when both session data and DRM connection are needed.
321         */
322        fsd_mutex_t drm_connection_mutex;
323
324        fsd_thread_t wait_thread_handle;
325        bool wait_thread_started;
326        bool wait_thread_run_flag;
327#endif
328};
329
330
331#endif /* __DRMAA_UTILS__SESSION_H */
332
Note: See TracBrowser for help on using the repository browser.