Class: PBS::Batch

Inherits:
Object
  • Object
show all
Defined in:
lib/pbs/batch.rb

Overview

Object used for simplified communication with a batch server

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(host:, prefix: '', lib: nil, bin: nil, **_) ⇒ Batch

Returns a new instance of Batch.

Parameters:

  • host (#to_s) —

    the batch server host

  • prefix (#to_s) (defaults to: '') —

    path to torque installation

  • lib (#to_s, nil) (defaults to: nil) —

    path to torque installation libraries

  • bin (#to_s, nil) (defaults to: nil) —

    path to torque installation binaries



46
47
48
49
50
51
 
# File 'lib/pbs/batch.rb', line 46

def initialize(host:, prefix: '', lib: nil, bin: nil, **_)
  @host    = host.to_s
  @prefix  = Pathname.new(prefix)
  @lib     = Pathname.new(lib) if lib
  @bin     = Pathname.new(bin) if bin
end

Instance Attribute Details

#host ⇒ String (readonly)

The host of the Torque batch server

Examples:

OSC’s Oakley batch server

my_conn.host #=> "oak-batch.osc.edu"

Returns:

  • (String) —

    the batch server host



10
11
12
 
# File 'lib/pbs/batch.rb', line 10

def host
  @host
end

Instance Method Details

#==(other) ⇒ Boolean

The comparison operator

Parameters:

  • other (#to_h) —

    batch server to compare against

Returns:

  • (Boolean) —

    how batch servers compare



62
63
64
 
# File 'lib/pbs/batch.rb', line 62

def ==(other)
  to_h == other.to_h
end

#bin ⇒ Pathname

The path to the Torque client installation binaries

Examples:

For Torque 5.0.0

my_conn.bin.to_s #=> "/usr/local/torque/5.0.0/bin"

Returns:

  • (Pathname) —

    path to torque binaries



33
34
35
36
37
38
39
40
 
# File 'lib/pbs/batch.rb', line 33

def bin
  @bin ||=
    if @prefix.join('bin').directory?
      @prefix.join('bin')
    else
      @prefix
    end
end

#connect {|cid| ... } ⇒ Object

Creates a connection to batch server and calls block in context of this connection

Yield Parameters:

  • cid (Fixnum) —

    connection id from established batch server connection

Yield Returns:

  • the final value of the block



84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/pbs/batch.rb', line 84

def connect(&block)
  Torque.lib = lib.join('libtorque.so')
  cid = Torque.pbs_connect(host)
  Torque.raise_error(cid.abs) if cid < 0  # raise error if negative connection id
  begin
    value = yield cid
  ensure
    Torque.pbs_disconnect(cid)            # always close connection
  end
  Torque.check_for_error                  # check for errors at end
  value
end

#delete_job(id) ⇒ void

This method returns an undefined value.

Delete a specified job from batch server

Examples:

Delete job ‘10219837.oak-batch.osc.edu’ from batch

my_conn.delete_job('10219837.oak-batch.osc.edu')

Parameters:

  • id (#to_s) —

    the id of the job



284
285
286
287
288
 
# File 'lib/pbs/batch.rb', line 284

def delete_job(id)
  connect do |cid|
    Torque.pbs_deljob cid, id.to_s, nil
  end
end

#eql?(other) ⇒ Boolean

Checks whether two batch server objects are completely identical to each other

Parameters:

  • other (Batch) —

    batch server to compare against

Returns:

  • (Boolean) —

    whether same objects



70
71
72
 
# File 'lib/pbs/batch.rb', line 70

def eql?(other)
  self.class == other.class && self == other
end

#get_job(id, **kwargs) ⇒ Hash

Get info for given batch server’s job

Examples:

Status info for OSC Oakley’s ‘10219837.oak-batch.osc.edu’ job

my_conn.get_job('102719837.oak-batch.osc.edu')
#=>
#{
#  "10219837.oak-batch.osc.edu" => {
#    :Job_Owner => "[email protected]",
#    :Job_Name => "CFD_Solver",
#    ...
#  }
#}

Parameters:

  • id (#to_s) —

    the id of requested information

  • filters (Array<Symbol>) —

    list of attribs to filter on

Returns:

  • (Hash) —

    hash with details of job



243
244
245
 
# File 'lib/pbs/batch.rb', line 243

def get_job(id, **kwargs)
  get_jobs(id: id, **kwargs)
end

#get_jobs(id: '', filters: []) ⇒ Hash

Get a list of hashes of the jobs on the batch server

Examples:

Status info for OSC Oakley jobs

my_conn.get_jobs
#=>
#{
#  "10219837.oak-batch.osc.edu" => {
#    :Job_Owner => "[email protected]",
#    :Job_Name => "CFD_Solver",
#    ...
#  },
#  "10219838.oak-batch.osc.edu" => {
#    :Job_Owner => "[email protected]",
#    :Job_Name => "FEA_Solver",
#    ...
#  },
#  ...
#}

Parameters:

  • id (#to_s) (defaults to: '') —

    the id of requested information

  • filters (Array<Symbol>) (defaults to: []) —

    list of attribs to filter on

Returns:

  • (Hash) —

    hash of details for jobs



222
223
224
225
226
227
228
 
# File 'lib/pbs/batch.rb', line 222

def get_jobs(id: '', filters: [])
  connect do |cid|
    filters = PBS::Torque::Attrl.from_list(filters)
    batch_status = Torque.pbs_statjob cid, id.to_s, filters, nil
    batch_status.to_h.tap { Torque.pbs_statfree batch_status }
  end
end

#get_node(id, **kwargs) ⇒ Hash

Get info for given batch server’s node

Examples:

Status info for OSC Oakley’s ‘n0001’ node

my_conn.get_node('n0001')
#=>
#{
#  "n0001" => {
#    :np => "12",
#    ...
#  }
#}

Parameters:

  • id (#to_s) —

    the id of requested information

  • filters (Array<Symbol>) —

    list of attribs to filter on

Returns:

  • (Hash) —

    status info for the node



198
199
200
 
# File 'lib/pbs/batch.rb', line 198

def get_node(id, **kwargs)
  get_nodes(id: id, **kwargs)
end

#get_nodes(id: '', filters: []) ⇒ Hash

Get a list of hashes of the nodes on the batch server

Examples:

Status info for OSC Oakley nodes

my_conn.get_nodes
#=>
#{
#  "n0001" => {
#    :np => "12",
#    ...
#  },
#  "n0002" => {
#    :np => "12",
#    ...
#  },
#  ...
#}

Parameters:

  • id (#to_s) (defaults to: '') —

    the id of requested information

  • filters (Array<Symbol>) (defaults to: []) —

    list of attribs to filter on

Returns:

  • (Hash) —

    hash of details for nodes



178
179
180
181
182
183
184
 
# File 'lib/pbs/batch.rb', line 178

def get_nodes(id: '', filters: [])
  connect do |cid|
    filters = PBS::Torque::Attrl.from_list(filters)
    batch_status = Torque.pbs_statnode cid, id.to_s, filters, nil
    batch_status.to_h.tap { Torque.pbs_statfree batch_status }
  end
end

#get_queue(id, **kwargs) ⇒ Hash

Get info for given batch server’s queue

Examples:

Status info for OSC Oakley’s parallel queue

my_conn.get_queue("parallel")
#=>
#{
#  "parallel" => {
#    :queue_type => "Execution",
#    ...
#  }
#}

Returns:

  • (Hash) —

    status info for the queue



155
156
157
 
# File 'lib/pbs/batch.rb', line 155

def get_queue(id, **kwargs)
  get_queues(id: id, **kwargs)
end

#get_queues(id: '', filters: []) ⇒ Hash

Get a list of hashes of the queues on the batch server

Examples:

Status info for OSC Oakley queues

my_conn.get_queues
#=>
#{
#  "parallel" => {
#    :queue_type => "Execution",
#    ...
#  },
#  "serial" => {
#    :queue_type => "Execution",
#    ...
#  },
#  ...
#}

Parameters:

  • id (#to_s) (defaults to: '') —

    the id of requested information

  • filters (Array<Symbol>) (defaults to: []) —

    list of attribs to filter on

Returns:

  • (Hash) —

    hash of details for the queues



135
136
137
138
139
140
141
 
# File 'lib/pbs/batch.rb', line 135

def get_queues(id: '', filters: [])
  connect do |cid|
    filters = PBS::Torque::Attrl.from_list(filters)
    batch_status = Torque.pbs_statque cid, id.to_s, filters, nil
    batch_status.to_h.tap { Torque.pbs_statfree batch_status }
  end
end

#get_status(filters: []) ⇒ Hash

Get a hash with status info for this batch server

Examples:

Status info for OSC Oakley batch server

my_conn.get_status
#=>
#{
#  "oak-batch.osc.edu:15001" => {
#    :server_state => "Idle",
#    ...
#  }
#}

Parameters:

  • filters (Array<Symbol>) (defaults to: []) —

    list of attribs to filter on

Returns:

  • (Hash) —

    status info for batch server



109
110
111
112
113
114
115
 
# File 'lib/pbs/batch.rb', line 109

def get_status(filters: [])
  connect do |cid|
    filters = PBS::Torque::Attrl.from_list filters
    batch_status = Torque.pbs_statserver cid, filters, nil
    batch_status.to_h.tap { Torque.pbs_statfree batch_status }
  end
end

#hash ⇒ Fixnum

Generates a hash value for this object

Returns:

  • (Fixnum) —

    hash value of object



76
77
78
 
# File 'lib/pbs/batch.rb', line 76

def hash
  [self.class, to_h].hash
end

#hold_job(id, type: :u) ⇒ void

This method returns an undefined value.

Put specified job on hold Possible hold types:

:u => Available to the owner of the job, the batch operator and the batch administrator
:o => Available to the batch operator and the batch administrator
:s => Available to the batch administrator

Examples:

Put job ‘10219837.oak-batch.osc.edu’ on hold

my_conn.hold_job('10219837.oak-batch.osc.edu')

Parameters:

  • id (#to_s) —

    the id of the job

  • type (Symbol) (defaults to: :u) —

    type of hold to be applied



257
258
259
260
261
 
# File 'lib/pbs/batch.rb', line 257

def hold_job(id, type: :u)
  connect do |cid|
    Torque.pbs_holdjob cid, id.to_s, type.to_s, nil
  end
end

#lib ⇒ Pathname

The path to the Torque client installation libraries

Examples:

For Torque 5.0.0

my_conn.lib.to_s #=> "/usr/local/torque/5.0.0/lib"

Returns:

  • (Pathname) —

    path to torque libraries



16
17
18
19
20
21
22
23
24
25
26
27
 
# File 'lib/pbs/batch.rb', line 16

def lib
  @lib ||=
    if @prefix.join('lib').directory?
      @prefix.join('lib')
    elsif @prefix.join('lib32').directory?
      @prefix.join('lib32')
    elsif @prefix.join('lib64').directory?
      @prefix.join('lib64')
    else
      @prefix
    end
end

#release_job(id, type: :u) ⇒ void

This method returns an undefined value.

Release a specified job that is on hold Possible hold types:

:u => Available to the owner of the job, the batch operator and the batch administrator
:o => Available to the batch operator and the batch administrator
:s => Available to the batch administrator

Examples:

Release job ‘10219837.oak-batch.osc.edu’ from hold

my_conn.release_job('10219837.oak-batch.osc.edu')

Parameters:

  • id (#to_s) —

    the id of the job

  • type (Symbol) (defaults to: :u) —

    type of hold to be removed



273
274
275
276
277
 
# File 'lib/pbs/batch.rb', line 273

def release_job(id, type: :u)
  connect do |cid|
    Torque.pbs_rlsjob cid, id.to_s, type.to_s, nil
  end
end

#submit_script(script, queue: nil, headers: {}, resources: {}, envvars: {}, qsub: true) ⇒ String

Submit a script to the batch server

Examples:

Submit a script with a few PBS directives

my_conn.submit_script("/path/to/script",
  headers: {
    Job_Name: "myjob",
    Join_Path: "oe"
  },
  resources: {
    nodes: "4:ppn=12",
    walltime: "12:00:00"
  },
  envvars: {
    TOKEN: "asd90f9sd8g90hk34"
  }
)
#=> "6621251.oak-batch.osc.edu"

Parameters:

  • script (#to_s) —

    path to the script

  • queue (#to_s) (defaults to: nil) —

    queue to submit script to

  • headers (Hash) (defaults to: {}) —

    pbs headers

  • resources (Hash) (defaults to: {}) —

    pbs resources

  • envvars (Hash) (defaults to: {}) —

    pbs environment variables

  • qsub (Boolean) (defaults to: true) —

    whether use library or binary for submission

Returns:

  • (String) —

    the id of the job that was created



313
314
315
 
# File 'lib/pbs/batch.rb', line 313

def submit_script(script, queue: nil, headers: {}, resources: {}, envvars: {}, qsub: true)
  send(qsub ? :qsub_submit : :pbs_submit, script, queue, headers, resources, envvars)
end

#submit_string(string, **kwargs) ⇒ String

Submit a script expanded into a string to the batch server

Parameters:

  • string (#to_s) —

    script as a string

  • script (#to_s) —

    path to the script

  • queue (#to_s) —

    queue to submit script to

  • headers (Hash) —

    pbs headers

  • resources (Hash) —

    pbs resources

  • envvars (Hash) —

    pbs environment variables

  • qsub (Boolean) —

    whether use library or binary for submission

Returns:

  • (String) —

    the id of the job that was created



321
322
323
324
325
326
327
 
# File 'lib/pbs/batch.rb', line 321

def submit_string(string, **kwargs)
  Tempfile.open('qsub.') do |f|
    f.write string.to_s
    f.close
    submit_script(f.path, **kwargs)
  end
end

#to_h ⇒ Hash

Convert object to hash

Returns:

  • (Hash) —

    the hash describing this object



55
56
57
 
# File 'lib/pbs/batch.rb', line 55

def to_h
  {host: host, lib: lib, bin: bin}
end