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

Returns a new instance of Batch.

Parameters:

  • host (#to_s) —

    the batch server host

  • lib (#to_s) (defaults to: "") —

    path to torque installation libraries

  • bin (#to_s) (defaults to: "") —

    path to torque installation binaries



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

#bin ⇒ Pathname (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"

Returns:

  • (Pathname) —

    path to torque binaries



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

def bin
  @bin
end

#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

#lib ⇒ Pathname (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"

Returns:

  • (Pathname) —

    path to torque libraries



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

def lib
  @lib
end

Instance Method Details

#==(other) ⇒ Boolean

The comparison operator

Parameters:

  • other (#to_h) —

    batch server to compare against

Returns:

  • (Boolean) —

    how batch servers compare



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

Parameters:

  • id (#to_s) —

    the id of the job



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

Parameters:

  • other (Batch) —

    batch server to compare against

Returns:

  • (Boolean) —

    whether same objects



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

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



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

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



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

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



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

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



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

Returns:

  • (Hash) —

    status info for the queue



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

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



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

Parameters:

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

    list of attribs to filter on

Returns:

  • (Hash) —

    status info for batch server



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

#hash ⇒ Fixnum

Generates a hash value for this object

Returns:

  • (Fixnum) —

    hash value of 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')

Parameters:

  • id (#to_s) —

    the id of the job

  • type (#to_s) (defaults to: :u) —

    type of hold to be applied



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

Parameters:

  • id (#to_s) —

    the id of the job

  • type (#to_s) (defaults to: :u) —

    type of hold to be removed



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

Parameters:

  • attribs (Array<#to_h>) (defaults to: []) —

    list of hashes describing attributes to select on

Returns:

  • (Hash) —

    hash of details of selected jobs



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

Parameters:

  • content (#to_s) —

    script as a string

  • args (Array<#to_s>) (defaults to: []) —

    arguments passed to ‘qsub` command

  • env (Hash{#to_s => #to_s}) (defaults to: {}) —

    environment variables set

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

    working directory where ‘qsub` is called from

Returns:

  • (String) —

    the id of the job that was created

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"

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



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

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



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_h ⇒ Hash

Convert object to hash

Returns:

  • (Hash) —

    the hash describing this object



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

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