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:, lib: "", bin: "", **_) ⇒ Batch


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

def initialize(host:, lib: "", bin: "", **_)
  @host    = host.to_s
  @lib     = Pathname.new(lib.to_s)
  @bin     = Pathname.new(bin.to_s)
end

Instance Attribute Details

#binPathname (readonly)

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"

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

def bin
  @bin
end

#hostString (readonly)

The host of the Torque batch server

Examples:

OSC's Oakley batch server

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

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

def host
  @host
end

#libPathname (readonly)

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"

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

def lib
  @lib
end

Instance Method Details

#==(other) ⇒ Boolean

The comparison operator


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

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


64
65
66
67
68
69
70
71
72
73
74
75
# File 'lib/pbs/batch.rb', line 64

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')

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

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


50
51
52
# File 'lib/pbs/batch.rb', line 50

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",
#    ...
#  }
#}

252
253
254
# File 'lib/pbs/batch.rb', line 252

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",
#    ...
#  },
#  ...
#}

231
232
233
234
235
236
237
# File 'lib/pbs/batch.rb', line 231

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",
#    ...
#  }
#}

178
179
180
# File 'lib/pbs/batch.rb', line 178

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",
#    ...
#  },
#  ...
#}

158
159
160
161
162
163
164
# File 'lib/pbs/batch.rb', line 158

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",
#    ...
#  }
#}

135
136
137
# File 'lib/pbs/batch.rb', line 135

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",
#    ...
#  },
#  ...
#}

115
116
117
118
119
120
121
# File 'lib/pbs/batch.rb', line 115

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",
#    ...
#  }
#}

89
90
91
92
93
94
95
# File 'lib/pbs/batch.rb', line 89

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

#hashFixnum

Generates a hash value for this object


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

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')

266
267
268
269
270
# File 'lib/pbs/batch.rb', line 266

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')

282
283
284
285
286
# File 'lib/pbs/batch.rb', line 282

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

#select_jobs(attribs: []) ⇒ Hash

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

Examples:

Status info for jobs owned by Bob

my_conn.select_jobs(attribs: [{name: "User_List", value: "bob", op: :eq}])
#=>
#{
#  "10219837.oak-batch.osc.edu" => {
#    :Job_Owner => "[email protected]",
#    :Job_Name => "CFD_Solver",
#    ...
#  },
#  "10219839.oak-batch.osc.edu" => {
#    :Job_Owner => "[email protected]",
#    :Job_Name => "CFD_Solver2",
#    ...
#  },
#  ...
#}

203
204
205
206
207
208
209
# File 'lib/pbs/batch.rb', line 203

def select_jobs(attribs: [])
  connect do |cid|
    attribs = PBS::Torque::Attropl.from_list(attribs.map(&:to_h))
    batch_status = Torque.pbs_selstat cid, attribs, nil
    batch_status.to_h.tap { Torque.pbs_statfree batch_status }
  end
end

#submit(content, args: [], env: {}, chdir: nil) ⇒ String

Submit a script expanded as a string to the batch server

Raises:

  • (Error)

    if `qsub` command exited unsuccessfully


347
348
349
# File 'lib/pbs/batch.rb', line 347

def submit(content, args: [], env: {}, chdir: nil)
  call(:qsub, *args, env: env, stdin: content, chdir: chdir).strip
end

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

Deprecated.

Use #submit instead.

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"

323
324
325
# File 'lib/pbs/batch.rb', line 323

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

#submit_string(string, **kwargs) ⇒ String

Deprecated.

Use #submit instead.

Submit a script expanded into a string to the batch server


332
333
334
335
336
337
338
# File 'lib/pbs/batch.rb', line 332

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_hHash

Convert object to hash


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

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