Logo Search packages:      
Sourcecode: pbs-drmaa version File versions

session.h

/* $Id: session.h 13 2011-04-20 15:41:43Z mmamonski $ */
/*
 *  FedStage DRMAA utilities library
 *  Copyright (C) 2006-2008  FedStage Systems
 *
 *  This program 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 of the License, or
 *  (at your option) any later version.
 *
 *  This program 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, see <http://www.gnu.org/licenses/>.
 */

/**
 * @file session.h
 * DRMAA session.
 */

#ifndef __DRMAA_UTILS__SESSION_H
#define __DRMAA_UTILS__SESSION_H

#include <sys/time.h>

#include <drmaa_utils/common.h>
#include <drmaa_utils/thread.h>

/** Creates new DRMAA session. */
fsd_drmaa_session_t *
fsd_drmaa_session_new( const char *contact );

/**
 * Get current (global) DRMAA session
 * and increase it's reference count.
 */
fsd_drmaa_session_t *
fsd_drmaa_session_get(void);

/**
 * An action to be taken when job is missing from queue.
 */
typedef enum {
      /**
       * Always raise #FSD_ERRNO_INTERNAL_ERROR (one per job)
       * in drmaa_wait() or drmaa_synchronize()
       * when job disappearance is spotted.
       */
      FSD_REVEAL_MISSING_JOBS,
      /**
       * Treat missing jobs as terminated with status
       * depending on last known state and action (drmaa_control()).
       */
      FSD_IGNORE_MISSING_JOBS,
      /**
       * Treat missing jobs as terminated
       * but only before they enter into running state.
       */
      FSD_IGNORE_QUEUED_MISSING_JOBS
} fsd_missing_jobs_behaviour_t;


/** DRMAA session data. */
00068 struct fsd_drmaa_session_s {
      /** Release one reference to DRMAA session. */
      void (*
00071       release)( fsd_drmaa_session_t *self );

      /**
       * Destroy session after ensuring no other references to it are held.
       *
       * May block until reference count decreases to 1.
       * May return before actual session destruction if another thread
       * have already taken responsibility for freeing session.
       */
      void (*
00081       destroy)(
                  fsd_drmaa_session_t *self );

      /**
       * Destroy session without waiting for releasing references.
       */
      void (*
00088       destroy_nowait)( fsd_drmaa_session_t *self );


      /** Implements drmaa_run_job(). */
      char* (*
00093       run_job)(
                  fsd_drmaa_session_t *self,
                  const fsd_template_t *jt
                  );

      /** Implements drmaa_run_bulk_jobs(). */
      fsd_iter_t* (*
00100       run_bulk)(
                  fsd_drmaa_session_t *self,
                  const fsd_template_t *jt,
                  int start, int end, int incr
                  );

      /** Implements drmaa_control(). */
      void (*
00108       control_job)(
                  fsd_drmaa_session_t *self,
                  const char *job_id, int action
                  );

      /** Implements drmaa_job_ps(). */
      void (*
00115       job_ps)(
                  fsd_drmaa_session_t *self,
                  const char *job_id, int *remote_ps
                  );

      /** Implements drmaa_synchronize(). */
      void (*
00122       synchronize)(
                  fsd_drmaa_session_t *self,
                  const char **input_job_ids, const struct timespec *timeout,
                  bool dispose
                  );

      /**
       * Implements drmaa_wait() call.
       * @param self     DRMAA session.
       * @param job_id   Job identifer to wait for or #DRMAA_JOB_IDS_SESSION_ANY
       * @param timeout  Timeout after which call shall raise
       *   #FSD_DRMAA_ERRNO_EXIT_TIMEOUT if job not terminated or \c NULL.
       * @param status   Terminated job status (output only).
       * @param rusage   Job resource usage (output only).
       * @see drmaa_wait()
       * @see #wait_for_single_job  #wait_for_any_job
       */
      char* (*
00140       wait)(
                  fsd_drmaa_session_t *self,
                  const char *job_id, const struct timespec *timeout,
                  int *status, fsd_iter_t **rusage
                  );

      /**
       * Construct new job object.
       * @return Reference to newly created job.
       */
      fsd_job_t* (*
00151       new_job)( fsd_drmaa_session_t *self, const char *job_id );

      char* (*
      run_impl)(
                  fsd_drmaa_session_t *self,
                  const fsd_template_t *jt, int bulk_incr
                  );

      /**
       * Wait until given job terminates (either successfuly or not).
       * @param self     DRMAA session.
       * @param job_id   Identifier of job to wait for.
       * @param timeout  If not \c NULL and job does not terminate
       *   in given amount of time function returns and
       *   #FSD_DRMAA_ERRNO_EXIT_TIMEOUT is raised.
       * @param status   If not \c NULL job status code is stored here.
       * @param rusage   If not \c NULL list of used resources is returned.
       * @param dispose  If \c true job information is removed from session
       *   at the end of call and further accesses to this job_id will
       *   raise #FSD_DRMAA_ERRNO_INVALID_JOB.  Otherwise job data is held.
       * @see #wait_for_any_job #wait
       */
      void (*
00174       wait_for_single_job)(
                  fsd_drmaa_session_t *self,
                  const char *job_id, const struct timespec *timeout,
                  int *status, fsd_iter_t **rusage, bool dispose
                  );

      /**
       * Wait until and job left in session terminates.
       * @return  Identifier of waited job.
       *   Freeing responsobility is left to the callee.
       * @see #wait_for_single_job #wait
       */
      char* (*
00187       wait_for_any_job)(
                  fsd_drmaa_session_t *self,
                  const struct timespec *timeout,
                  int *status, fsd_iter_t **rusage,
                  bool dispose
                  );

      void (*
      wait_for_job_status_change)(
                  fsd_drmaa_session_t *self,
                  fsd_cond_t *wait_condition,
                  fsd_mutex_t *mutex,
                  const struct timespec *timeout
                  );

      void* (*
      wait_thread)( fsd_drmaa_session_t *self );

      void (*
      stop_wait_thread)( fsd_drmaa_session_t *self );

      /**
       * Make status of all jobs held in session up to date.
       */
      void (*
00212       update_all_jobs_status)( fsd_drmaa_session_t *self );

      /** Return list of all jobs within session. */
      char** (*
00216       get_submited_job_ids)(
                  fsd_drmaa_session_t *self
                  );

      /**
       * Get job with given identifier.
       * @return New reference to job or \c NULL
       *   if no job found.
       */
      fsd_job_t* (*
00226       get_job)(
                  fsd_drmaa_session_t *self, const char *job_id
                  );

      /**
       * Tries to load configuration from following locations in order
       * (configuration settings from later locations override
       * those from earlier):
       * /etc/basename.conf, ~/.basename.conf, $basename_CONF.
       */
      void (*
00237       load_configuration)(
                  fsd_drmaa_session_t *self, const char *basename
                  );

      void (*
      read_configuration)(
                  fsd_drmaa_session_t *self,
                  const char *filename, bool must_exist,
                  const char *configuration, size_t config_len
                  );

      void (*
      apply_configuration)(
                  fsd_drmaa_session_t *self
                  );

      /** Reference counter. */
00254       int ref_cnt;

      /**
       * Whether #destroy was called and waits for releasing
       * references.  If set pending #wait calls shall
       * return with #FSD_DRMAA_ERRNO_NO_ACTIVE_SESSION error.
       */
00261       bool destroy_requested;

      /**
       * Copy of contact string passed to drmaa_init()
       * or default contact if drmaa_init() was called with \c NULL.
       */
00267       char *contact;

      /**
       * Jobs submitted within this DRMAA session
       * and not disposed yet.
       */
00273       fsd_job_set_t *jobs;

      /** DRMAA configuration. */
00276       fsd_conf_dict_t *configuration;

      /** Queue pooling delay (time delta). */
00279       struct timespec pool_delay;

      /**
       * Cache job state for number of seconds.
       * If positive drmaa_job_ps() returns remembered state without
       * communicating with DRM for \a cache_job_state seconds since last
       * update.
       */
00287       int cache_job_state;

      /** Whether to wait for jobs in separate thread. */
00290       bool enable_wait_thread;

      /**
       * Configuration dictionary which maps
       * job categories to native specification.
       */
00296       fsd_conf_dict_t *job_categories;

      /**
       * How to behave when submitted job disappears from DRM queue.
       */
00301       fsd_missing_jobs_behaviour_t missing_jobs;

00303       fsd_mutex_t mutex; /**< Mutex for accessing session data. */
00304       fsd_cond_t wait_condition;  /**< Conditional for drmaa_wait() */
00305       fsd_cond_t destroy_condition;  /**< Conditional for ref_cnt==1 */

      /**
       * Mutex for accessing connection to DRM.
       *
       * To prevent deadlocks #mutex should be acquired first
       * when both session data and DRM connection are needed.
       */
00313       fsd_mutex_t drm_connection_mutex;

      fsd_thread_t wait_thread_handle;
      bool wait_thread_started;
      bool wait_thread_run_flag;
};


00321 typedef struct fsd_drmaa_ctx_s {
      fsd_drmaa_session_t *session;
      fsd_mutex_t session_mutex;
      
} fsd_drmaa_ctx_t;


extern fsd_drmaa_ctx_t fsd_drmaa_ctx;

#endif /* __DRMAA_UTILS__SESSION_H */


Generated by  Doxygen 1.6.0   Back to index