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: nil, **_) ⇒ Batch

Returns a new instance of Batch.

Parameters:

  • host (#to_s) —

    the batch server host

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

    path to torque installation



20
21
22
23
 
# File 'lib/pbs/batch.rb', line 20

def initialize(host:, prefix: nil, **_)
  @host    = host.to_s
  @prefix  = Pathname.new(prefix) if prefix
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

#prefix ⇒ Pathname? (readonly)

The path to the Torque client installation

Examples:

For Torque 5.0.0

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

Returns:

  • (Pathname, nil) —

    path to torque installation



16
17
18
 
# File 'lib/pbs/batch.rb', line 16

def prefix
  @prefix
end

Instance Method Details

#==(other) ⇒ Boolean

The comparison operator

Parameters:

  • other (#to_h) —

    batch server to compare against

Returns:

  • (Boolean) —

    how batch servers compare



34
35
36
 
# File 'lib/pbs/batch.rb', line 34

def ==(other)
  to_h == other.to_h
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



56
57
58
59
60
61
62
63
64
65
66
67
 
# File 'lib/pbs/batch.rb', line 56

def connect(&block)
  Torque.lib = prefix ? prefix.join('lib', 'libtorque.so') : nil
  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



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

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



42
43
44
 
# File 'lib/pbs/batch.rb', line 42

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



215
216
217
 
# File 'lib/pbs/batch.rb', line 215

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



194
195
196
197
198
199
200
 
# File 'lib/pbs/batch.rb', line 194

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



170
171
172
 
# File 'lib/pbs/batch.rb', line 170

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



150
151
152
153
154
155
156
 
# File 'lib/pbs/batch.rb', line 150

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



127
128
129
 
# File 'lib/pbs/batch.rb', line 127

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



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

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



81
82
83
84
85
86
87
 
# File 'lib/pbs/batch.rb', line 81

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



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

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



229
230
231
232
233
 
# File 'lib/pbs/batch.rb', line 229

def hold_job(id, type: :u)
  connect do |cid|
    Torque.pbs_holdjob cid, id.to_s, type.to_s, nil
  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



245
246
247
248
249
 
# File 'lib/pbs/batch.rb', line 245

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



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

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



293
294
295
296
297
298
299
 
# File 'lib/pbs/batch.rb', line 293

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



27
28
29
 
# File 'lib/pbs/batch.rb', line 27

def to_h
  {host: host, prefix: prefix}
end