pbs 1.1.4 → 2.0.0

data/lib/pbs/torque.rb

@@ -1,73 +1,190 @@
-require "ffi"
+require 'ffi'
 
 module PBS
+  # An interface to the C-library of Torque
   module Torque
     extend FFI::Library
 
-    # Define torque methods using a supplied library
-    def self.init(args = {})
-      @@lib = args[:lib] || "torque"
+    # @!attribute [rw] self.pbs_errno
+    #   The internal PBS error number
+    #     int pbs_errno
+    #   @return [Fixnum] pbs error number
 
-      # Set up FFI to use this library
-      ffi_lib @@lib
+    # @!attribute [r] self.pbs_server
+    #   The PBS server name
+    #     char *pbs_server
+    #   @return [String] pbs server name
 
-      # int pbs_errno
-      attach_variable :pbs_errno, :int
+    # @!method self.pbs_strerror(errno)
+    #   Generates PBS error string from given error number
+    #     char *pbs_strerror(int errno)
+    #   @param errno [Fixnum] pbs error number
+    #   @return [String] pbs error string
 
-      # char *pbs_server
-      attach_variable :pbs_server, :string
+    # @!method self.pbs_default
+    #   Default PBS server name
+    #     char *pbs_default(void)
+    #   @see http://linux.die.net/man/3/pbs_default
+    #   @return [String] default pbs server name
 
-      # int pbs_connect(char *server)
-      attach_function :pbs_connect, [ :pointer ], :int
+    # @!method self.pbs_connect(server)
+    #   Connect to PBS batch server
+    #     int pbs_connect(char *server)
+    #   @see http://linux.die.net/man/3/pbs_connect
+    #   @param server [String] name of pbs server
+    #   @return [Fixnum] connection identifier
 
-      # char *pbs_default(void)
-      attach_function :pbs_default, [], :string
+    # @!method self.pbs_disconnect(connect)
+    #   Disconnect from a PBS batch server
+    #     int pbs_disconnect(int connect)
+    #   @see http://linux.die.net/man/3/pbs_disconnect
+    #   @param connect [Fixnum] connection identifier
+    #   @return [Fixnum] exit status code
 
-      # char *pbs_strerror(int errno)
-      attach_function :pbs_strerror, [ :int ], :string
+    # @!method self.pbs_deljob(connect, job_id, extend)
+    #   Delete a PBS batch job
+    #     int pbs_deljob(int connect, char *job_id, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_deljob
+    #   @param connect [Fixnum] connection identifier
+    #   @param job_id [String] the job id
+    #   @param extend [String] implementation defined extensions
+    #   @return [Fixnum] exit status code
 
-      # int pbs_deljob(int connect, char *job_id, char *extend)
-      attach_function :pbs_deljob, [ :int, :pointer, :pointer ], :int
+    # @!method self.pbs_holdjob(connect, job_id, hold_type, extend)
+    #   Place a hold on a PBS batch job
+    #     int pbs_holdjob(int connect, char *job_id, char *hold_type, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_holdjob
+    #   @param connect [Fixnum] connection identifier
+    #   @param job_id [String] the job id
+    #   @param hold_type [String] type of hold to be applied
+    #   @param extend [String] implementation defined extensions
+    #   @return [Fixnum] exit status code
 
-      # int pbs_disconnect(int connect)
-      attach_function :pbs_disconnect, [ :int ], :int
+    # @!method self.pbs_rlsjob(connect, job_id, hold_type, extend)
+    #   Release a hold on a PBS batch job
+    #     int pbs_rlsjob(int connect, char *job_id, char *hold_type, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_rlsjob
+    #   @param connect [Fixnum] connection identifier
+    #   @param job_id [String] the job id
+    #   @param hold_type [String] type of hold to be released
+    #   @param extend [String] implementation defined extensions
+    #   @return [Fixnum] exit status code
 
-      # int pbs_holdjob(int connect, char *job_id, char *hold_type, char *extend)
-      attach_function :pbs_holdjob, [ :int, :pointer, :pointer, :pointer ], :int
+    # @!method self.pbs_statfree(stat)
+    #   Free the memory allocated by {BatchStatus} object
+    #     void pbs_statfree(struct batch_status *stat)
+    #   @param stat [BatchStatus] the batch status object
+    #   @return [void]
 
-      # int pbs_rlsjob(int connect, char *job_id, char *hold_type, char *extend)
-      attach_function :pbs_rlsjob, [ :int, :pointer, :pointer, :pointer ], :int
+    # @!method self.pbs_statjob(connect, id, attrib, extend)
+    #   Obtain status of PBS batch jobs
+    #     batch_status * pbs_statjob(int connect, char *id, struct attrl *attrib, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_statjob
+    #   @param connect [Fixnum] connection identifier
+    #   @param id [String] job or destination identifier
+    #   @param attrib [Attrl] the attribute c-linked list object
+    #   @param extend [String] implementation defined extensions
+    #   @return [BatchStatus] c-linked list of batch status objects
+    #   @note It is up to the user to free the space of the batch status objects
 
-      # void pbs_statfree(struct batch_status *stat)
-      attach_function :pbs_statfree, [ :pointer ], :void
+    # @!method self.pbs_statnode(connect, id, attrib, extend)
+    #   Obtain status of PBS nodes
+    #     batch_status * pbs_statnode(int connect, char *id, struct attrl *attrib, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_statnode
+    #   @param connect [Fixnum] connection identifier
+    #   @param id [String] name of a node or null string
+    #   @param attrib [Attrl] the attribute c-linked list object
+    #   @param extend [String] implementation defined extensions
+    #   @return [BatchStatus] c-linked list of batch status objects
+    #   @note It is up to the user to free the space of the batch status objects
 
-      # batch_status * pbs_statjob(int connect, char *id, struct attrl *attrib, char *extend)
-      attach_function :pbs_statjob, [ :int, :pointer, :pointer, :pointer ], BatchStatus.ptr
+    # @!method self.pbs_statque(connect, id, attrib, extend)
+    #   Obtain status of PBS batch queues
+    #     batch_status * pbs_statque(int connect, char *id, struct attrl *attrib, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_statque
+    #   @param connect [Fixnum] connection identifier
+    #   @param id [String] name of a queue or null string
+    #   @param attrib [Attrl] the attribute c-linked list object
+    #   @param extend [String] implementation defined extensions
+    #   @return [BatchStatus] c-linked list of batch status objects
+    #   @note It is up to the user to free the space of the batch status objects
 
-      # batch_status * pbs_statnode(int connect, char *id, struct attrl *attrib, char *extend)
-      attach_function :pbs_statnode, [ :int, :pointer, :pointer, :pointer ], BatchStatus.ptr
+    # @!method self.pbs_statserver(connect, attrib, extend)
+    #   Obtain status of a PBS batch server
+    #     batch_status * pbs_statserver(int connect, struct attrl *attrib, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_statserver
+    #   @param connect [Fixnum] connection identifier
+    #   @param attrib [Attrl] the attribute c-linked list object
+    #   @param extend [String] implementation defined extensions
+    #   @return [BatchStatus] c-linked list of batch status objects
+    #   @note It is up to the user to free the space of the batch status objects
 
-      # batch_status * pbs_statque(int connect, char *id, struct attrl *attrib, char *extend)
-      attach_function :pbs_statque, [ :int, :pointer, :pointer, :pointer ], BatchStatus.ptr
+    # @!method self.pbs_submit(connect, attrib, script, destination, extend)
+    #   Submit a PBS batch job
+    #     char *pbs_submit(int connect, struct attropl *attrib, char *script, char *destination, char *extend)
+    #   @see http://linux.die.net/man/3/pbs_submit
+    #   @param connect [Fixnum] connection identifier
+    #   @param attrib [Attropl] the attribute operation c-linked list object
+    #   @param script [String] the path to the script
+    #   @param destination [String] the queue to send job to
+    #   @param extend [String] implementation defined extensions
+    #   @return [String] the job id
 
-      # batch_status * pbs_statserver(int connect, struct attrl *attrib, char *extend)
-      attach_function :pbs_statserver, [ :int, :pointer, :pointer ], BatchStatus.ptr
+    # The path to the torque library file
+    # @return [String] path to torque library
+    def self.lib
+      @lib
+    end
+
+    # Define torque methods using a supplied library
+    # @param lib [#to_s, nil] path to library file
+    # @return [void]
+    def self.lib=(lib)
+      @lib = lib ? lib.to_s : 'torque'
 
-      # char *pbs_submit(int connect, struct attropl *attrib, char *script, char *destination, char *extend)
-      attach_function :pbs_submit, [ :int, :pointer, :pointer, :pointer, :pointer ], :string
+      # Set up FFI to use this library
+      ffi_lib @lib
+
+      attach_variable :pbs_errno, :int
+      attach_variable :pbs_server, :string
+      attach_function :pbs_strerror, [ :int ], :string
+      attach_function :pbs_default, [], :string
+      attach_function :pbs_connect, [ :string ], :int
+      attach_function :pbs_disconnect, [ :int ], :int
+      attach_function :pbs_deljob, [ :int, :string, :string ], :int
+      attach_function :pbs_holdjob, [ :int, :string, :string, :string ], :int
+      attach_function :pbs_rlsjob, [ :int, :string, :string, :string ], :int
+      attach_function :pbs_statfree, [ BatchStatus.ptr ], :void
+      attach_function :pbs_statjob, [ :int, :string, Attrl.ptr, :string ], BatchStatus.ptr
+      attach_function :pbs_statnode, [ :int, :string, Attrl.ptr, :string ], BatchStatus.ptr
+      attach_function :pbs_statque, [ :int, :string, Attrl.ptr, :string ], BatchStatus.ptr
+      attach_function :pbs_statserver, [ :int, Attrl.ptr, :string ], BatchStatus.ptr
+
+      # FIXME: The space for the job_identifier string is allocated by
+      # pbs_submit() and should be released via a call to free() when no longer
+      # needed
+      attach_function :pbs_submit, [ :int, Attropl.ptr, :string, :string, :string ], :string
     end
 
+    # Check for any errors set in the errno
+    # @return [void]
     def self.check_for_error
       errno = pbs_errno
       self.pbs_errno = 0  # reset error number
       raise_error(errno) if errno > 0
     end
 
+    # For a given errno, raise the corresponding error with error message
+    # @param errno [Fixnum] the error number
+    # @raise [Error] if errno is not 0
+    # @return [void]
     def self.raise_error(errno)
       raise (ERROR_CODES[errno] || PBS::Error), "#{pbs_strerror(errno)}"
     end
 
+    #
     # Data structures defined in pbs_ifl.h
+    #
 
     # Enum for Batch Operation
     BatchOp = enum(:set, :unset, :incr, :decr, :eq, :ne, :ge, :gt, :le, :lt, :dflt, :merge, :incr_old)
@@ -80,34 +197,31 @@ module PBS
              :value,    :pointer,         # string for value of attribute
              :op,       BatchOp           # not used in an Attrl object
 
+      # Given an array of attribute names convert it to {Attrl} C-linked list
+      # @param list [Array<Symbol>] list of attribute names
+      # @return [Attrl] generated attribute c-linked list object
       def self.from_list(list)
         attrl = nil
         prev = Attrl.new(FFI::Pointer::NULL)
         list.each do |key|
           attrl = Attrl.new
           attrl[:name] = FFI::MemoryPointer.from_string(key.to_s)
-          attrl[:resource] = FFI::Pointer::NULL
-          attrl[:value] = FFI::Pointer::NULL
-          attrl[:op] = 0
           attrl[:next] = prev
           prev = attrl
         end
         attrl
       end
 
-      def to_hash
-        hash = Hash.new{ |h,k| h[k] = Hash.new() }
+      # Convert to hash describing this linked list
+      # @return [Hash] hash describing linked list
+      def to_h
         attrl = self
+        hash = {}
         until attrl.to_ptr.null?
-          name = attrl[:name].read_string.to_sym
-          value = attrl[:value].read_string
-          resource = nil
-          resource = attrl[:resource].read_string.to_sym unless attrl[:resource].null?
-          if resource.nil?
-            hash[name] = value
-          else
-            hash[name][resource] = value
-          end
+          n = attrl[:name].read_string
+          v = attrl[:value].read_string
+          r = attrl[:resource].null? ? nil : attrl[:resource].read_string
+          r ? (hash[n.to_sym] ||= {} and hash[n.to_sym][r.to_sym] = v) : hash[n.to_sym] = v
           attrl = attrl[:next]
         end
         hash
@@ -122,6 +236,9 @@ module PBS
              :value,    :pointer,         # string for value of attribute
              :op,       BatchOp           # operation to perform for this attribute
 
+      # Convert to C-linked list of structs from hash
+      # @param hash [Hash] hash representation of this c-linked list
+      # @return [Attropl] generated attribute operation c-linked list object
       def self.from_hash(hash)
         # Convert hash into array
         # Format: {name: value, name: {resource: value, resource: value}}
@@ -131,41 +248,42 @@ module PBS
         prev = Attropl.new(FFI::Pointer::NULL)
         ary.each do |attrib|
           attropl = Attropl.new
-          attropl[:name] = FFI::MemoryPointer.from_string(attrib[0].to_s)
-          attropl[:value] = FFI::MemoryPointer.from_string(attrib[1])
-          attropl[:resource] = FFI::MemoryPointer.from_string(attrib[2].to_s) unless attrib[2].nil?
-          attropl[:op] = 0
-          attropl[:next] = prev
+          attropl[:name]     = FFI::MemoryPointer.from_string attrib[0].to_s
+          attropl[:value]    = FFI::MemoryPointer.from_string attrib[1].to_s
+          attropl[:resource] = FFI::MemoryPointer.from_string attrib[2].to_s if attrib[2]
+          attropl[:next]     = prev
           prev = attropl
         end
         attropl
       end
     end
 
-    # Struct for status of batch
+    # Struct for PBS batch server status responses
     class BatchStatus < FFI::ManagedStruct
       layout :next,     BatchStatus.ptr,  # pointer to next BatchStatus object
              :name,     :string,          # string for name of this status
              :attribs,  Attrl.ptr,        # pointer to beginning of C-linked list of an Attrl object
              :text,     :string           # string containing unknown text
 
+      # Free memory for allocated {BatchStatus} C-linked list
       def self.release(ptr)
         pbs_statfree(ptr)
       end
 
-      def to_a
-        ary = []
+      # Convert to hash describing this linked list
+      # @return [Hash] hash describing linked list
+      def to_h
         batch = self
+        hash = {}
         until batch.to_ptr.null?
-          ary << {name: batch[:name], attribs: batch[:attribs].to_hash}
+          hash[batch[:name]] = batch[:attribs].to_h
           batch = batch[:next]
         end
-        ary
+        hash
       end
     end
 
-    # Defined error codes
-    # valid as of Torque >=4.2.10
+    # Defined error codes, valid as of Torque >=4.2.10
     ERROR_CODES = {
       15001 => PBS::UnkjobidError,
       15002 => PBS::NoattrError,

data/lib/pbs/version.rb

@@ -1,3 +1,4 @@
 module PBS
-  VERSION = "1.1.4"
+  # The current version of PBS
+  VERSION = "2.0.0"
 end

data/pbs.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.platform      = Gem::Platform::RUBY
   spec.authors       = ["Jeremy Nicklas"]
   spec.email         = ["jnicklas@osc.edu"]
-  spec.summary       = %q{PBS FFI Ruby gem to use FFI to interface with Adaptive Computing's resource manager Torque}
-  spec.description   = %q{PBS FFI Ruby gem to use FFI to interface with Adaptive Computing's resource manager Torque}
+  spec.summary       = %q{Ruby gem that uses FFI to interface with Adaptive Computing's resource manager Torque}
+  spec.description   = %q{Ruby wrapper for the Torque C library utilizing Ruby-FFI. This has been successfully tested with Torque 4.2.10 and greater. Your mileage may vary.}
   spec.homepage      = "https://github.com/OSC/pbs-ruby"
   spec.license       = "MIT"
 
@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
+  spec.required_ruby_version = '~> 2.2'
 
   spec.add_runtime_dependency "ffi", "~> 1.9", ">= 1.9.6"
   spec.add_development_dependency "bundler", "~> 1.7"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pbs
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 2.0.0
 platform: ruby
 authors:
 - Jeremy Nicklas
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-07 00:00:00.000000000 Z
+date: 2016-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -58,8 +58,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '10.0'
-description: PBS FFI Ruby gem to use FFI to interface with Adaptive Computing's resource
-  manager Torque
+description: Ruby wrapper for the Torque C library utilizing Ruby-FFI. This has been
+  successfully tested with Torque 4.2.10 and greater. Your mileage may vary.
 email:
 - jnicklas@osc.edu
 executables: []
@@ -67,20 +67,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
-- config/batch.yml
-- config/websvcs02.osc.edu.yml
-- config/websvcs08.osc.edu.yml
-- examples/simplejob.rb
 - lib/pbs.rb
 - lib/pbs/attributes.rb
-- lib/pbs/conn.rb
+- lib/pbs/batch.rb
 - lib/pbs/error.rb
-- lib/pbs/job.rb
-- lib/pbs/query.rb
 - lib/pbs/torque.rb
 - lib/pbs/version.rb
 - pbs.gemspec
@@ -94,9 +89,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -104,9 +99,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.8
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
-summary: PBS FFI Ruby gem to use FFI to interface with Adaptive Computing's resource
-  manager Torque
+summary: Ruby gem that uses FFI to interface with Adaptive Computing's resource manager
+  Torque
 test_files: []
+has_rdoc: 

data/config/batch.yml

@@ -1,24 +0,0 @@
-oakley: &oakley
-    lib: '/usr/local/torque/default/lib/libtorque.so'
-    server: &oakley_server 'oak-batch.osc.edu'
-    qsub: 'LD_LIBRARY_PATH=/usr/local/torque/default/lib:$LD_LIBRARY_PATH /usr/local/torque/default/bin/qsub'
-*oakley_server:
-  <<: *oakley
-ruby: &ruby
-    lib: '/usr/local/torque/default/lib/libtorque.so'
-    server: &ruby_server 'ruby-batch.ten.osc.edu'
-    qsub: 'LD_LIBRARY_PATH=/usr/local/torque/default/lib:$LD_LIBRARY_PATH /usr/local/torque/default/bin/qsub'
-*ruby_server:
-  <<: *ruby
-oxymoron: &oxymoron
-    lib: '/usr/local/torque/default/lib/libtorque.so'
-    server: &oxymoron_server 'oak-batch.osc.edu:17001'
-    qsub: 'LD_LIBRARY_PATH=/usr/local/torque/default/lib:$LD_LIBRARY_PATH /usr/local/torque/default/bin/qsub'
-*oxymoron_server:
-  <<: *oxymoron
-quick: &quick
-    lib: '/usr/local/torque/default/lib/libtorque.so'
-    server: &quick_server 'quick-batch.osc.edu'
-    qsub: 'LD_LIBRARY_PATH=/usr/local/torque/default/lib:$LD_LIBRARY_PATH /usr/local/torque/default/bin/qsub'
-*quick_server:
-  <<: *quick