ood_core 0.0.1

data/lib/ood_core/job/adapters/torque.rb

@@ -0,0 +1,274 @@
+require "ood_core/refinements/hash_extensions"
+
+gem "pbs", "~> 2.0"
+require "pbs"
+
+module OodCore
+  module Job
+    class Factory
+      using Refinements::HashExtensions
+
+      # Build the Torque adapter from a configuration
+      # @param config [#to_h] the configuration for job adapter
+      # @option config [#to_s] :host The batch server host
+      # @option config [#to_s] :lib ('') Path to torque client libraries
+      # @option config [#to_s] :bin ('') Path to torque client binaries
+      def self.build_torque(config)
+        c = config.to_h.symbolize_keys
+        host = c.fetch(:host) { raise ArgumentError, "No host specified. Missing argument: host" }.to_s
+        lib  = c.fetch(:lib, "").to_s
+        bin  = c.fetch(:bin, "").to_s
+        pbs  = PBS::Batch.new(host: host, lib: lib, bin: bin)
+        Adapters::Torque.new(pbs: pbs)
+      end
+    end
+
+    module Adapters
+      # An adapter object that describes the communication with a Torque resource
+      # manager for job management.
+      class Torque < Adapter
+        using Refinements::HashExtensions
+
+        # Mapping of state characters for PBS
+        STATE_MAP = {
+          'Q' => :queued,
+          'H' => :queued_held,
+          'T' => :queued_held,    # transiting, most like a held job
+          'R' => :running,
+          'S' => :suspended,
+          'E' => :running,        # exiting, but still running
+          'C' => :completed
+        }
+
+        # @api private
+        # @param opts [#to_h] the options defining this adapter
+        # @option opts [PBS::Batch] :pbs The PBS batch object
+        # @see Factory.build_torque
+        def initialize(opts = {})
+          o = opts.to_h.symbolize_keys
+
+          @pbs = o.fetch(:pbs) { raise ArgumentError, "No pbs object specified. Missing argument: pbs" }
+        end
+
+        # Submit a job with the attributes defined in the job template instance
+        # @param script [Script] script object that describes the
+        #   script and attributes for the submitted job
+        # @param after [#to_s, Array<#to_s>] this job may be scheduled for execution
+        #   at any point after dependent jobs have started execution
+        # @param afterok [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution only after dependent jobs have terminated with no errors
+        # @param afternotok [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution only after dependent jobs have terminated with errors
+        # @param afterany [#to_s, Array<#to_s>] this job may be scheduled for
+        #   execution after dependent jobs have terminated
+        # @raise [JobAdapterError] if something goes wrong submitting a job
+        # @return [String] the job id returned after successfully submitting a job
+        # @see Adapter#submit
+        def submit(script, after: [], afterok: [], afternotok: [], afterany: [])
+          after      = Array(after).map(&:to_s)
+          afterok    = Array(afterok).map(&:to_s)
+          afternotok = Array(afternotok).map(&:to_s)
+          afterany   = Array(afterany).map(&:to_s)
+
+          # Set headers
+          headers = {}
+          headers.merge!(job_arguments: script.args.join(' ')) unless script.args.nil?
+          headers.merge!(Hold_Types: :u) if script.submit_as_hold
+          headers.merge!(Rerunable: script.rerunnable ? 'y' : 'n') unless script.rerunnable.nil?
+          headers.merge!(init_work_dir: script.workdir) unless script.workdir.nil?
+          headers.merge!(Mail_Users: script.email.join(',')) unless script.email.nil?
+          mail_points  = ''
+          mail_points += 'b' if script.email_on_started
+          mail_points += 'e' if script.email_on_terminated
+          headers.merge!(Mail_Points: mail_points) unless mail_points.empty?
+          headers.merge!(Job_Name: script.job_name) unless script.job_name.nil?
+          # ignore input_path (not defined in Torque)
+          headers.merge!(Output_Path: script.output_path) unless script.output_path.nil?
+          headers.merge!(Error_Path: script.error_path) unless script.error_path.nil?
+          headers.merge!(Join_Path: 'oe') if script.join_files
+          headers.merge!(reservation_id: script.reservation_id) unless script.reservation_id.nil?
+          headers.merge!(Priority: script.priority) unless script.priority.nil?
+          headers.merge!(Execution_Time: script.start_time.localtime.strftime("%C%y%m%d%H%M.%S")) unless script.start_time.nil?
+          headers.merge!(Account_Name: script.accounting_id) unless script.accounting_id.nil?
+
+          # Set dependencies
+          depend = []
+          depend << "after:#{after.join(':')}"           unless after.empty?
+          depend << "afterok:#{afterok.join(':')}"       unless afterok.empty?
+          depend << "afternotok:#{afternotok.join(':')}" unless afternotok.empty?
+          depend << "afterany:#{afterany.join(':')}"     unless afterany.empty?
+          headers.merge!(depend: depend.join(','))       unless depend.empty?
+
+          # Set resources
+          resources = {}
+          resources.merge!(mem: "#{script.min_phys_memory}KB") unless script.min_phys_memory.nil?
+          resources.merge!(walltime: seconds_to_duration(script.wall_time)) unless script.wall_time.nil?
+          if script.nodes && !script.nodes.empty?
+            # Reduce an array to unique objects with count
+            #   ["a", "a", "b"] #=> {"a" => 2, "b" => 1}
+            nodes = script.nodes.group_by {|v| v}.each_with_object({}) {|(k, v), h| h[k] = v.size}
+            resources.merge!(nodes: nodes.map {|k, v| k.is_a?(NodeRequest) ? node_request_to_str(k, v) : k }.join('+'))
+          end
+
+          # Set environment variables
+          envvars = script.job_environment || {}
+
+          # Set native options
+          if script.native
+            headers.merge!   script.native.fetch(:headers, {})
+            resources.merge! script.native.fetch(:resources, {})
+            envvars.merge!   script.native.fetch(:envvars, {})
+          end
+
+          # Submit job
+          @pbs.submit_string(script.content, queue: script.queue_name, headers: headers, resources: resources, envvars: envvars)
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Retrieve info for all jobs from the resource manager
+        # @raise [JobAdapterError] if something goes wrong getting job info
+        # @return [Array<Info>] information describing submitted jobs
+        # @see Adapter#info_all
+        def info_all
+          @pbs.get_jobs.map do |k, v|
+            parse_job_info(k, v)
+          end
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Retrieve job info from the resource manager
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong getting job info
+        # @return [Info] information describing submitted job
+        # @see Adapter#info
+        def info(id)
+          id = id.to_s
+          parse_job_info(*@pbs.get_job(id).flatten)
+        rescue PBS::UnkjobidError
+          # set completed status if can't find job id
+          Info.new(
+            id: id,
+            status: :completed
+          )
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Retrieve job status from resource manager
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong getting job status
+        # @return [Status] status of job
+        # @see Adapter#status
+        def status(id)
+          id = id.to_s
+          char = @pbs.get_job(id, filters: [:job_state])[id][:job_state]
+          Status.new(state: STATE_MAP.fetch(char, :undetermined))
+        rescue PBS::UnkjobidError
+          # set completed status if can't find job id
+          Status.new(state: :completed)
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Put the submitted job on hold
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong holding a job
+        # @return [void]
+        # @see Adapter#hold
+        def hold(id)
+          @pbs.hold_job(id.to_s)
+        rescue PBS::UnkjobidError
+          # assume successful job hold if can't find job id
+          nil
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Release the job that is on hold
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong releasing a job
+        # @return [void]
+        # @see Adapter#release
+        def release(id)
+          @pbs.release_job(id.to_s)
+        rescue PBS::UnkjobidError
+          # assume successful job release if can't find job id
+          nil
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        # Delete the submitted job
+        # @param id [#to_s] the id of the job
+        # @raise [JobAdapterError] if something goes wrong deleting a job
+        # @return [void]
+        # @see Adapter#delete
+        def delete(id)
+          @pbs.delete_job(id.to_s)
+        rescue PBS::UnkjobidError, PBS::BadstateError
+          # assume successful job deletion if can't find job id
+          # assume successful job deletion if job is exiting or completed
+          nil
+        rescue PBS::Error => e
+          raise JobAdapterError, e.message
+        end
+
+        private
+          # Convert duration to seconds
+          def duration_in_seconds(time)
+            time.nil? ? 0 : time.split(':').map { |v| v.to_i }.inject(0) { |total, v| total * 60 + v }
+          end
+
+          # Convert seconds to duration
+          def seconds_to_duration(time)
+            '%02d:%02d:%02d' % [time/3600, time/60%60, time%60]
+          end
+
+          # Convert host list string to individual nodes
+          # "n0163/2,7,10-11+n0205/0-11+n0156/0-11"
+          def parse_nodes(node_list)
+            node_list.split('+').map do |n|
+              name, procs_list = n.split('/')
+              # count procs used in range expression
+              procs = procs_list.split(',').inject(0) do |sum, x|
+                sum + (x =~ /^(\d+)-(\d+)$/ ? ($2.to_i - $1.to_i) : 0) + 1
+              end
+              {name: name, procs: procs}
+            end
+          end
+
+          # Convert a NodeRequest object to a valid Torque string
+          def node_request_to_str(node, cnt)
+            str = cnt.to_s
+            str += ":ppn=#{node.procs}" if node.procs
+            str += ":#{node.properties.join(':')}" if node.properties
+            str
+          end
+
+          # Parse hash describing PBS job status
+          def parse_job_info(k, v)
+            /^(?<job_owner>[\w-]+)@/ =~ v[:Job_Owner]
+            allocated_nodes = parse_nodes(v[:exec_host] || "")
+            Info.new(
+              id: k,
+              status: STATE_MAP.fetch(v[:job_state], :undetermined),
+              allocated_nodes: allocated_nodes,
+              submit_host: v[:submit_host],
+              job_name: v[:Job_Name],
+              job_owner: job_owner,
+              accounting_id: v[:Account_Name],
+              procs: allocated_nodes.inject(0) { |sum, x| sum + x[:procs] },
+              queue_name: v[:queue],
+              wallclock_time: duration_in_seconds(v.fetch(:resources_used, {})[:walltime]),
+              cpu_time: duration_in_seconds(v.fetch(:resources_used, {})[:cput]),
+              submission_time: v[:ctime],
+              dispatch_time: v[:start_time],
+              native: v
+            )
+          end
+      end
+    end
+  end
+end

data/lib/ood_core/job/factory.rb

@@ -0,0 +1,41 @@
+require "ood_core/refinements/hash_extensions"
+
+module OodCore
+  module Job
+    # A factory that builds job adapter objects from a configuration.
+    class Factory
+      using Refinements::HashExtensions
+
+      class << self
+        # Build a job adapter from a configuration
+        # @param config [#to_h] configuration describing job adapter
+        # @option config [#to_s] :adapter The job adapter to use
+        # @raise [AdapterNotSpecified] if no adapter is specified
+        # @raise [AdapterNotFound] if the specified adapter does not exist
+        # @return [Adapter] the job adapter object
+        def build(config)
+          c = config.to_h.symbolize_keys
+
+          adapter = c.fetch(:adapter) { raise AdapterNotSpecified, "job configuration does not specify adapter" }.to_s
+
+          path_to_adapter = "ood_core/job/adapters/#{adapter}"
+          begin
+            require path_to_adapter
+          rescue Gem::LoadError => e
+            raise Gem::LoadError, "Specified '#{adapter}' for job adapter, but the gem is not loaded."
+          rescue LoadError => e
+            raise LoadError, "Could not load '#{adapter}'. Make sure that the job adapter in the configuration file is valid."
+          end
+
+          adapter_method = "build_#{adapter}"
+
+          unless respond_to?(adapter_method)
+            raise AdapterNotFound, "job configuration specifies nonexistent #{adapter} adapter"
+          end
+
+          send(adapter_method, c)
+        end
+      end
+    end
+  end
+end

data/lib/ood_core/job/info.rb

@@ -0,0 +1,141 @@
+require 'time'
+
+module OodCore
+  module Job
+    # An object that describes a submitted job
+    class Info
+      # The identifier of the job
+      # @return [String] job id
+      attr_reader :id
+
+      # The status of the job
+      # @return [Status] job state
+      attr_reader :status
+
+      # Set of machines that is utilized for job execution
+      # @return [Array<NodeInfo>] allocated nodes
+      attr_reader :allocated_nodes
+
+      # Name of the submission host for this job
+      # @return [String, nil] submit host
+      attr_reader :submit_host
+
+      # Name of the job
+      # @return [String, nil] job name
+      attr_reader :job_name
+
+      # Owner of job
+      # @return [String, nil] job owner
+      attr_reader :job_owner
+
+      # The account the job is charged against
+      # @return [String, nil] accounting id
+      attr_reader :accounting_id
+
+      # Number of procs allocated for job
+      # @return [Fixnum, nil] allocated total number of procs
+      attr_reader :procs
+
+      # Name of the queue in which the job was queued or started
+      # @return [String, nil] queue name
+      attr_reader :queue_name
+
+      # The accumulated wall clock time in seconds
+      # @return [Fixnum, nil] wallclock time
+      attr_reader :wallclock_time
+
+      # The accumulated CPU time in seconds
+      # @return [Fixnum, nil] cpu time
+      attr_reader :cpu_time
+
+      # The time at which the job was submitted
+      # @return [Time, nil] submission time
+      attr_reader :submission_time
+
+      # The time the job first entered a "Started" state
+      # @return [Time, nil] dispatch time
+      attr_reader :dispatch_time
+
+      # Native resource manager output for job info
+      # @note Should not be used by generic apps
+      # @return [Object] native info
+      attr_reader :native
+
+      # @param id [#to_s] job id
+      # @param status [#to_sym] job state
+      # @param allocated_nodes [Array<#to_h>] allocated nodes
+      # @param submit_host [#to_s, nil] submit host
+      # @param job_name [#to_s, nil] job name
+      # @param job_owner [#to_s, nil] job owner
+      # @param accounting_id [#to_s, nil] accounting id
+      # @param procs [#to_i, nil] allocated total number of procs
+      # @param queue_name [#to_s, nil] queue name
+      # @param wallclock_time [#to_i, nil] wallclock time
+      # @param cpu_time [#to_i, nil] cpu time
+      # @param submission_time [#to_i, nil] submission time
+      # @param dispatch_time [#to_i, nil] dispatch time
+      # @param native [Object] native info
+      def initialize(id:, status:, allocated_nodes: [], submit_host: nil,
+                     job_name: nil, job_owner: nil, accounting_id: nil,
+                     procs: nil, queue_name: nil, wallclock_time: nil,
+                     cpu_time: nil, submission_time: nil, dispatch_time: nil,
+                     native: nil, **_)
+        @id              = id.to_s
+        @status          = Status.new(state: status.to_sym)
+        @allocated_nodes = allocated_nodes.map { |n| NodeInfo.new(n.to_h) }
+        @submit_host     = submit_host     && submit_host.to_s
+        @job_name        = job_name        && job_name.to_s
+        @job_owner       = job_owner       && job_owner.to_s
+        @accounting_id   = accounting_id   && accounting_id.to_s
+        @procs           = procs           && procs.to_i
+        @queue_name      = queue_name      && queue_name.to_s
+        @wallclock_time  = wallclock_time  && wallclock_time.to_i
+        @cpu_time        = cpu_time        && cpu_time.to_i
+        @submission_time = submission_time && Time.at(submission_time.to_i)
+        @dispatch_time   = dispatch_time   && Time.at(dispatch_time.to_i)
+        @native          = native
+      end
+
+      # Convert object to hash
+      # @return [Hash] object as hash
+      def to_h
+        {
+          id:              id,
+          status:          status,
+          allocated_nodes: allocated_nodes,
+          submit_host:     submit_host,
+          job_name:        job_name,
+          job_owner:       job_owner,
+          accounting_id:   accounting_id,
+          procs:           procs,
+          queue_name:      queue_name,
+          wallclock_time:  wallclock_time,
+          cpu_time:        cpu_time,
+          submission_time: submission_time,
+          dispatch_time:   dispatch_time,
+          native:          native
+        }
+      end
+
+      # The comparison operator
+      # @param other [#to_h] object to compare against
+      # @return [Boolean] whether objects are equivalent
+      def ==(other)
+        to_h == other.to_h
+      end
+
+      # Whether objects are identical to each other
+      # @param other [#to_h] object to compare against
+      # @return [Boolean] whether objects are identical
+      def eql?(other)
+        self.class == other.class && self == other
+      end
+
+      # Generate a hash value for this object
+      # @return [Fixnum] hash value of object
+      def hash
+        [self.class, to_h].hash
+      end
+    end
+  end
+end