ood_core 0.0.1

data/lib/ood_core/job/node_info.rb

@@ -0,0 +1,47 @@
+module OodCore
+  module Job
+    # An object that describes the resources used on a specific node
+    class NodeInfo
+      # The name of the host machine
+      # @return [String] node name
+      attr_reader :name
+
+      # The number of procs reserved on the given machine
+      # @return [Fixnum, nil] number of procs
+      attr_reader :procs
+
+      # @param name [#to_s] node name
+      # @param procs [#to_i, nil] number of procs
+      def initialize(name:, procs: nil, **_)
+        @name  = name.to_s
+        @procs = procs && procs.to_i
+      end
+
+      # Convert object to hash
+      # @return [Hash] object as hash
+      def to_h
+        { name: name, procs: procs }
+      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

data/lib/ood_core/job/node_request.rb

@@ -0,0 +1,51 @@
+require 'ood_core/refinements/array_extensions'
+
+module OodCore
+  module Job
+    # An object that describes a request for a node when submitting a job
+    class NodeRequest
+      using Refinements::ArrayExtensions
+
+      # Number of processors usable by job
+      # @return [Fixnum, nil] number of procs
+      attr_reader :procs
+
+      # List of properties required by job
+      # @return [Array<String>, nil] list of properties
+      attr_reader :properties
+
+      # @param procs [#to_i, nil] number of procs
+      # @param properties [#to_s, Array<#to_s>, nil] list of properties
+      def initialize(procs: nil, properties: nil, **_)
+        @procs      = procs      && procs.to_i
+        @properties = properties && Array.wrap(properties).map(&:to_s)
+      end
+
+      # Convert object to hash
+      # @return [Hash] object as hash
+      def to_h
+        { procs: procs, properties: properties }
+      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

data/lib/ood_core/job/script.rb

@@ -0,0 +1,235 @@
+require 'pathname'
+require 'time'
+require 'ood_core/refinements/array_extensions'
+
+module OodCore
+  module Job
+    # An object that describes a batch job before it is submitted. This includes
+    # the resources this batch job will require of the resource manager.
+    class Script
+      using Refinements::ArrayExtensions
+
+      # Content of the script to be executed on the remote host
+      # @return [String] the script content
+      attr_reader :content
+
+      # Arguments supplied to script to be executed
+      # @return [Array<String>, nil] arguments supplied to script
+      attr_reader :args
+
+      # Whether job is held after submitted
+      # @return [Boolean, nil] whether job is held after submit
+      attr_reader :submit_as_hold
+
+      # Whether job can safely be restarted by the resource manager, for example on
+      # node failure or some other re-scheduling event
+      # @note This SHOULD NOT be used to let the application denote the
+      #   checkpointability of a job
+      # @return [Boolean, nil] whether job can be restarted
+      attr_reader :rerunnable
+
+      # Environment variables to be set on remote host when running job
+      # @note These will override the remote host environment settings
+      # @return [Hash{String=>String}, nil] environment variables
+      attr_reader :job_environment
+
+      # Directory where the job is executed from
+      # @return [Pathname, nil] working directory
+      attr_reader :workdir
+
+      # List of email addresses that should be used when resource manager sends
+      # status notifications
+      # @return [Array<String>, nil] list of emails
+      attr_reader :email
+
+      # Whether given email addresses should be notified when job starts
+      # @return [Boolean, nil] whether email when job starts
+      attr_reader :email_on_started
+
+      # Whether given email addresses should be notified when job ends
+      # @return [Boolean, nil] whether email when job ends
+      attr_reader :email_on_terminated
+
+      # The name of the job
+      # @return [String, nil] name of job
+      attr_reader :job_name
+
+      # Path to file specifying the input stream of the job
+      # @return [Pathname, nil] file path specifying input stream
+      attr_reader :input_path
+
+      # Path to file specifying the output stream of the job
+      # @return [Pathname, nil] file path specifying output stream
+      attr_reader :output_path
+
+      # Path to file specifying the error stream of the job
+      # @return [Pathname, nil] file path specifying error stream
+      attr_reader :error_path
+
+      # Whether the error stream should be intermixed with the output stream
+      # @return [Boolean, nil] whether error stream intermixed with output stream
+      attr_reader :join_files
+
+      # Identifier of existing reservation to be associated with the job
+      # @return [String, nil] reservation id
+      attr_reader :reservation_id
+
+      # Name of the queue the job should be submitted to
+      # @return [String, nil] queue name
+      attr_reader :queue_name
+
+      # The scheduling priority for the job
+      # @return [Fixnum, nil] scheduling priority
+      attr_reader :priority
+
+      # The minmimum amount of physical memory in kilobyte that should be available
+      # for the job
+      # @return [Fixnum, nil] minimum physical memory
+      attr_reader :min_phys_memory
+
+      # The earliest time when the job may be eligible to run
+      # @return [Time, nil] eligible start time
+      attr_reader :start_time
+
+      # The maximum amount of real time during which the job can be running in
+      # seconds
+      # @return [Fixnum, nil] max real time
+      attr_reader :wall_time
+
+      # The attribute used for job accounting purposes
+      # @return [String, nil] accounting id
+      attr_reader :accounting_id
+
+      # Node or list of nodes detailing the specifications the job should run on
+      # @example Job to run on a list of defined nodes
+      #   my_script.nodes
+      #   #=> ["n0001", "n0002", "n0003"]
+      # @example Job to run on 2 nodes with 12 procs per node
+      #   my_script.nodes
+      #   #=> [
+      #   #     #<OodCore::Job::NodeRequest procs=12, properties={}>,
+      #   #     #<OodCore::Job::NodeRequest procs=12, properties={}>
+      #   #   ]
+      # @example Create job script that will run on 100 nodes with 20 procs per node
+      #   OodCore::Job::Script.new(
+      #     script: Pathname.new('/path/to/script'),
+      #     nodes: [OodCore::Job::NodeRequest.new(procs: 20)] * 100
+      #   )
+      # @return [Array<String, NodeRequest>, nil] list of nodes
+      attr_reader :nodes
+
+      # Object detailing any native specifications that are implementation specific
+      # @note Should not be used at all costs.
+      # @return [Object, nil] native specifications
+      attr_reader :native
+
+      # @param content [#to_s] the script content
+      # @param args [Array<#to_s>, nil] arguments supplied to script
+      # @param submit_as_hold [Boolean, nil] whether job is held after submit
+      # @param rerunnable [Boolean, nil] whether job can be restarted
+      # @param job_environment [Hash{#to_s => #to_s}, nil] environment variables
+      # @param workdir [#to_s, nil] working directory
+      # @param email [#to_s, Array<#to_s>, nil] list of emails
+      # @param email_on_started [Boolean, nil] whether email when job starts
+      # @param email_on_terminated [Boolean, nil] whether email when job ends
+      # @param job_name [#to_s, nil] name of job
+      # @param input_path [#to_s, nil] file path specifying input stream
+      # @param output_path [#to_s, nil] file path specifying output stream
+      # @param error_path [#to_s, nil] file path specifying error stream
+      # @param join_files [Boolean, nil] whether error stream intermixed with output stream
+      # @param reservation_id [#to_s, nil] reservation id
+      # @param queue_name [#to_s, nil] queue name
+      # @param priority [#to_i, nil] scheduling priority
+      # @param min_phys_memory [#to_i, nil] minimum physical memory
+      # @param start_time [#to_i, nil] eligible start time
+      # @param wall_time [#to_i, nil] max real time
+      # @param accounting_id [#to_s, nil] accounting id
+      # @param nodes [#to_h, #to_s, Array<#to_h, #to_s>, nil] list of nodes
+      # @param native [Object, nil] native specifications
+      def initialize(content:, args: nil, submit_as_hold: nil, rerunnable: nil,
+                     job_environment: nil, workdir: nil, email: nil,
+                     email_on_started: nil, email_on_terminated: nil, job_name: nil,
+                     input_path: nil, output_path: nil, error_path: nil,
+                     join_files: nil, reservation_id: nil, queue_name: nil,
+                     priority: nil, min_phys_memory: nil, start_time: nil,
+                     wall_time: nil, accounting_id: nil, nodes: nil, native: nil,
+                     **_)
+        @content = content.to_s
+
+        @submit_as_hold      = submit_as_hold
+        @rerunnable          = rerunnable
+        @email_on_started    = email_on_started
+        @email_on_terminated = email_on_terminated
+        @join_files          = join_files
+
+        @args             = args            && args.map(&:to_s)
+        @job_environment  = job_environment && job_environment.each_with_object({}) { |(k, v), h| h[k.to_s] = v.to_s }
+        @workdir          = workdir         && Pathname.new(workdir.to_s)
+        @email            = email           && Array.wrap(email).map(&:to_s)
+        @job_name         = job_name        && job_name.to_s
+        @input_path       = input_path      && Pathname.new(input_path.to_s)
+        @output_path      = output_path     && Pathname.new(output_path.to_s)
+        @error_path       = error_path      && Pathname.new(error_path.to_s)
+        @reservation_id   = reservation_id  && reservation_id.to_s
+        @queue_name       = queue_name      && queue_name.to_s
+        @priority         = priority        && priority.to_i
+        @min_phys_memory  = min_phys_memory && min_phys_memory.to_i
+        @start_time       = start_time      && Time.at(start_time.to_i)
+        @wall_time        = wall_time       && wall_time.to_i
+        @accounting_id    = accounting_id   && accounting_id.to_s
+        @nodes            = nodes           && Array.wrap(nodes).map { |n| n.respond_to?(:to_h) ? NodeRequest.new(n.to_h) : n.to_s }
+        @native           = native
+      end
+
+      # Convert object to hash
+      # @return [Hash] object as hash
+      def to_h
+        {
+          content:             content,
+          args:                args,
+          submit_as_hold:      submit_as_hold,
+          rerunnable:          rerunnable,
+          job_environment:     job_environment,
+          workdir:             workdir,
+          email:               email,
+          email_on_started:    email_on_started,
+          email_on_terminated: email_on_terminated,
+          job_name:            job_name,
+          input_path:          input_path,
+          output_path:         output_path,
+          error_path:          error_path,
+          join_files:          join_files,
+          reservation_id:      reservation_id,
+          queue_name:          queue_name,
+          priority:            priority,
+          min_phys_memory:     min_phys_memory,
+          start_time:          start_time,
+          wall_time:           wall_time,
+          accounting_id:       accounting_id,
+          nodes:               nodes,
+          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

data/lib/ood_core/job/status.rb

@@ -0,0 +1,128 @@
+module OodCore
+  module Job
+    # An object that describes the current state of a submitted job
+    class Status
+      class << self
+        # Possible states a submitted job can be in:
+        #   # Job status cannot be determined
+        #   :undetermined
+        #
+        #   # Job is queued for being scheduled and executed
+        #   :queued
+        #
+        #   # Job has been placed on hold by the system, the administrator, or
+        #   # submitting user
+        #   :queued_held
+        #
+        #   # Job is running on an execution host
+        #   :running
+        #
+        #   # Job has been suspended by the user, the system, or the administrator
+        #   :suspended
+        #
+        #   # Job is completed and not running on an execution host
+        #   :completed
+        def states
+          %i(
+            undetermined
+            queued
+            queued_held
+            running
+            suspended
+            completed
+          )
+        end
+      end
+
+      # Current status of submitted job
+      # @return [Symbol] status of job
+      attr_reader :state
+
+      # @param state [#to_sym] status of job
+      # @raise [UnknownStateAttribute] if supplied state does not exist
+      def initialize(state:, **_)
+        @state = state.to_sym
+        raise UnknownStateAttribute, "arguments specify unknown '#{@state}' state" unless self.class.states.include?(@state)
+      end
+
+      # Convert object to symbol
+      # @return [Symbol] object as symbol
+      def to_sym
+        state
+      end
+
+      # Convert object to string
+      # @return [String] object as string
+      def to_s
+        state.to_s
+      end
+
+      # The comparison operator
+      # @param other [#to_sym] object to compare against
+      # @return [Boolean] whether objects are equivalent
+      def ==(other)
+        to_sym == other.to_sym
+      end
+
+      # Whether objects are identical to each other
+      # @param other [#to_sym] 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_sym].hash
+      end
+
+      # @!method undetermined?
+      #   Whether the status is undetermined
+      #   @return [Boolean] whether undetermined
+      #
+      # @!method queued?
+      #   Whether the status is queued
+      #   @return [Boolean] whether queued
+      #
+      # @!method queued_held?
+      #   Whether the status is queued_held
+      #   @return [Boolean] whether queued_held
+      #
+      # @!method running?
+      #   Whether the status is running
+      #   @return [Boolean] whether running
+      #
+      # @!method suspended?
+      #   Whether the status is suspended
+      #   @return [Boolean] whether suspended
+      #
+      # @!method completed?
+      #   Whether the status is completed
+      #   @return [Boolean] whether completed
+      #
+      # Determine whether this method corresponds to a status check for a valid
+      # state. If so, then check whether this object is in that valid state.
+      # @param method_name the method name called
+      # @param arguments the arguments to the call
+      # @param block an optional block for the call
+      # @raise [NoMethodError] if method name doesn't pass checks
+      # @return [Boolean] whether it is in this state
+      def method_missing(method_name, *arguments, &block)
+        if /^(?<other_state>.+)\?$/ =~ method_name && self.class.states.include?(other_state.to_sym)
+          self == other_state
+        else
+          super
+        end
+      end
+
+      # Determines whether this method corresponds to a status check for a valid
+      # state
+      # @param method_name the method name called
+      # @return [Boolean]
+      def respond_to_missing?(method_name, include_private = false)
+        /^(?<other_state>.+)\?$/ =~ method_name && self.class.states.include?(other_state.to_sym) || super
+      end
+    end
+  end
+end