Class: Lockfile

Inherits:
Object
  • Object
show all
Defined in:
lib/rq/lockfile.rb

Defined Under Namespace

Classes: LockError, MaxTriesLockError, NFSLockError, SleepCycle, StackingLockError, StatLockError, StolenLockError, TimeoutLockError, UnLockError

Constant Summary collapse

VERSION =

–{{{

'1.4.3'
HOSTNAME =
Socket::gethostname
DEFAULT_RETRIES =

maximum number of attempts

nil
DEFAULT_TIMEOUT =

the longest we will try

nil
DEFAULT_MAX_AGE =

lockfiles older than this are stale

3600
DEFAULT_SLEEP_INC =

sleep cycle is this much longer each time

2
DEFAULT_MIN_SLEEP =

shortest sleep time

2
DEFAULT_MAX_SLEEP =

longest sleep time

32
DEFAULT_SUSPEND =

iff we steal a lock wait this long before we go on

1800
DEFAULT_REFRESH =

how often we touch/validate the lock

8
DEFAULT_DONT_CLEAN =

iff we leave lock files lying around

false
DEFAULT_POLL_RETRIES =

this many polls makes one ‘try’

16
DEFAULT_POLL_MAX_SLEEP =

the longest we’ll sleep between polls

0.08
DEFAULT_DONT_SWEEP =

if we cleanup after other process on our host

false
DEFAULT_DONT_USE_LOCK_ID =

if we dump lock info into lockfile

false
DEFAULT_DEBUG =
ENV['LOCKFILE_DEBUG'] || false

Class Attribute Summary collapse

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(path, opts = {}, &block) ⇒ Lockfile

Returns a new instance of Lockfile.



170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
# File 'lib/rq/lockfile.rb', line 170

def initialize(path, opts = {}, &block)
#--{{{
  @klass = self.class
  @path  = path
  @opts  = opts

  @retries          = getopt 'retries'          , @klass.retries
  @max_age          = getopt 'max_age'          , @klass.max_age
  @sleep_inc        = getopt 'sleep_inc'        , @klass.sleep_inc
  @min_sleep        = getopt 'min_sleep'        , @klass.min_sleep
  @max_sleep        = getopt 'max_sleep'        , @klass.max_sleep
  @suspend          = getopt 'suspend'          , @klass.suspend
  @timeout          = getopt 'timeout'          , @klass.timeout
  @refresh          = getopt 'refresh'          , @klass.refresh
  @dont_clean       = getopt 'dont_clean'       , @klass.dont_clean
  @poll_retries     = getopt 'poll_retries'     , @klass.poll_retries
  @poll_max_sleep   = getopt 'poll_max_sleep'   , @klass.poll_max_sleep
  @dont_sweep       = getopt 'dont_sweep'       , @klass.dont_sweep
  @dont_use_lock_id = getopt 'dont_use_lock_id' , @klass.dont_use_lock_id
  @debug            = getopt 'debug'            , @klass.debug

  @sleep_cycle = SleepCycle::new @min_sleep, @max_sleep, @sleep_inc 

  @clean    = @dont_clean ? nil : lambda{ File::unlink @path rescue nil }
  @dirname  = File::dirname @path
  @basename = File::basename @path
  @thief    = false
  @locked   = false

  lock(&block) if block
#--}}}
end

Class Attribute Details

.debugObject

Returns the value of attribute debug.



84
85
86
# File 'lib/rq/lockfile.rb', line 84

def debug
  @debug
end

.dont_cleanObject

Returns the value of attribute dont_clean.



85
86
87
# File 'lib/rq/lockfile.rb', line 85

def dont_clean
  @dont_clean
end

.dont_sweepObject

Returns the value of attribute dont_sweep.



88
89
90
# File 'lib/rq/lockfile.rb', line 88

def dont_sweep
  @dont_sweep
end

.dont_use_lock_idObject

Returns the value of attribute dont_use_lock_id.



89
90
91
# File 'lib/rq/lockfile.rb', line 89

def dont_use_lock_id
  @dont_use_lock_id
end

.max_ageObject

Returns the value of attribute max_age.



77
78
79
# File 'lib/rq/lockfile.rb', line 77

def max_age
  @max_age
end

.max_sleepObject

Returns the value of attribute max_sleep.



80
81
82
# File 'lib/rq/lockfile.rb', line 80

def max_sleep
  @max_sleep
end

.min_sleepObject

Returns the value of attribute min_sleep.



79
80
81
# File 'lib/rq/lockfile.rb', line 79

def min_sleep
  @min_sleep
end

.poll_max_sleepObject

Returns the value of attribute poll_max_sleep.



87
88
89
# File 'lib/rq/lockfile.rb', line 87

def poll_max_sleep
  @poll_max_sleep
end

.poll_retriesObject

Returns the value of attribute poll_retries.



86
87
88
# File 'lib/rq/lockfile.rb', line 86

def poll_retries
  @poll_retries
end

.refreshObject

Returns the value of attribute refresh.



83
84
85
# File 'lib/rq/lockfile.rb', line 83

def refresh
  @refresh
end

.retriesObject

–{{{



76
77
78
# File 'lib/rq/lockfile.rb', line 76

def retries
  @retries
end

.sleep_incObject

Returns the value of attribute sleep_inc.



78
79
80
# File 'lib/rq/lockfile.rb', line 78

def sleep_inc
  @sleep_inc
end

.suspendObject

Returns the value of attribute suspend.



81
82
83
# File 'lib/rq/lockfile.rb', line 81

def suspend
  @suspend
end

.timeoutObject

Returns the value of attribute timeout.



82
83
84
# File 'lib/rq/lockfile.rb', line 82

def timeout
  @timeout
end

Instance Attribute Details

#basenameObject (readonly)

Returns the value of attribute basename.



123
124
125
# File 'lib/rq/lockfile.rb', line 123

def basename
  @basename
end

#cleanObject (readonly)

Returns the value of attribute clean.



124
125
126
# File 'lib/rq/lockfile.rb', line 124

def clean
  @clean
end

#debugObject Also known as: debug?

Returns the value of attribute debug.



139
140
141
# File 'lib/rq/lockfile.rb', line 139

def debug
  @debug
end

#dirnameObject (readonly)

Returns the value of attribute dirname.



122
123
124
# File 'lib/rq/lockfile.rb', line 122

def dirname
  @dirname
end

#dont_cleanObject (readonly)

Returns the value of attribute dont_clean.



133
134
135
# File 'lib/rq/lockfile.rb', line 133

def dont_clean
  @dont_clean
end

#dont_sweepObject (readonly)

Returns the value of attribute dont_sweep.



136
137
138
# File 'lib/rq/lockfile.rb', line 136

def dont_sweep
  @dont_sweep
end

#dont_use_lock_idObject (readonly)

Returns the value of attribute dont_use_lock_id.



137
138
139
# File 'lib/rq/lockfile.rb', line 137

def dont_use_lock_id
  @dont_use_lock_id
end

#klassObject (readonly)

Returns the value of attribute klass.



117
118
119
# File 'lib/rq/lockfile.rb', line 117

def klass
  @klass
end

#lockedObject (readonly) Also known as: locked?

Returns the value of attribute locked.



120
121
122
# File 'lib/rq/lockfile.rb', line 120

def locked
  @locked
end

#max_ageObject (readonly)

Returns the value of attribute max_age.



126
127
128
# File 'lib/rq/lockfile.rb', line 126

def max_age
  @max_age
end

#max_sleepObject (readonly)

Returns the value of attribute max_sleep.



129
130
131
# File 'lib/rq/lockfile.rb', line 129

def max_sleep
  @max_sleep
end

#min_sleepObject (readonly)

Returns the value of attribute min_sleep.



128
129
130
# File 'lib/rq/lockfile.rb', line 128

def min_sleep
  @min_sleep
end

#optsObject (readonly)

Returns the value of attribute opts.



119
120
121
# File 'lib/rq/lockfile.rb', line 119

def opts
  @opts
end

#pathObject (readonly)

Returns the value of attribute path.



118
119
120
# File 'lib/rq/lockfile.rb', line 118

def path
  @path
end

#poll_max_sleepObject (readonly)

Returns the value of attribute poll_max_sleep.



135
136
137
# File 'lib/rq/lockfile.rb', line 135

def poll_max_sleep
  @poll_max_sleep
end

#poll_retriesObject (readonly)

Returns the value of attribute poll_retries.



134
135
136
# File 'lib/rq/lockfile.rb', line 134

def poll_retries
  @poll_retries
end

#refreshObject (readonly)

Returns the value of attribute refresh.



131
132
133
# File 'lib/rq/lockfile.rb', line 131

def refresh
  @refresh
end

#retriesObject (readonly)

Returns the value of attribute retries.



125
126
127
# File 'lib/rq/lockfile.rb', line 125

def retries
  @retries
end

#sleep_incObject (readonly)

Returns the value of attribute sleep_inc.



127
128
129
# File 'lib/rq/lockfile.rb', line 127

def sleep_inc
  @sleep_inc
end

#suspendObject (readonly)

Returns the value of attribute suspend.



130
131
132
# File 'lib/rq/lockfile.rb', line 130

def suspend
  @suspend
end

#thiefObject (readonly) Also known as: thief?

Returns the value of attribute thief.



121
122
123
# File 'lib/rq/lockfile.rb', line 121

def thief
  @thief
end

#timeoutObject (readonly)

Returns the value of attribute timeout.



132
133
134
# File 'lib/rq/lockfile.rb', line 132

def timeout
  @timeout
end

Class Method Details

.create(path, *a, &b) ⇒ Object



145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
# File 'lib/rq/lockfile.rb', line 145

def self::create(path, *a, &b)
#--{{{
  opts = {
    'retries' => 0,
    'min_sleep' => 0,
    'max_sleep' => 1,
    'sleep_inc' => 1,
    'max_age' => nil,
    'suspend' => 0,
    'refresh' => nil,
    'timeout' => nil,
    'poll_retries' => 0,
    'dont_clean' => true,
    'dont_sweep' => false,
    'dont_use_lock_id' => true,
  }
  begin
    new(path, opts).lock
  rescue LockError
    raise Errno::EEXIST, path
  end
  open(path, *a, &b)
#--}}}
end

.initObject



91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
# File 'lib/rq/lockfile.rb', line 91

def init
#--{{{
  @retries          = DEFAULT_RETRIES
  @max_age          = DEFAULT_MAX_AGE
  @sleep_inc        = DEFAULT_SLEEP_INC
  @min_sleep        = DEFAULT_MIN_SLEEP
  @max_sleep        = DEFAULT_MAX_SLEEP
  @suspend          = DEFAULT_SUSPEND
  @timeout          = DEFAULT_TIMEOUT
  @refresh          = DEFAULT_REFRESH
  @dont_clean       = DEFAULT_DONT_CLEAN
  @poll_retries     = DEFAULT_POLL_RETRIES
  @poll_max_sleep   = DEFAULT_POLL_MAX_SLEEP
  @dont_sweep       = DEFAULT_DONT_SWEEP
  @dont_use_lock_id = DEFAULT_DONT_USE_LOCK_ID

  @debug          = DEFAULT_DEBUG

  STDOUT.sync = true if @debug
  STDERR.sync = true if @debug
#--}}}
end

Instance Method Details

#alive?(pid) ⇒ Boolean

—-}}}

Returns:

  • (Boolean)


347
348
349
350
351
352
353
354
355
356
357
# File 'lib/rq/lockfile.rb', line 347

def alive? pid
#----{{{
  pid = Integer("#{ pid }")
  begin
    Process::kill 0, pid
    true
  rescue Errno::ESRCH
    false
  end
#----}}}
end

#attemptObject

–}}}



536
537
538
539
540
541
542
# File 'lib/rq/lockfile.rb', line 536

def attempt
#----{{{
  ret = nil
  loop{ break unless catch('attempt'){ ret = yield } == 'try_again' }
  ret
#----}}}
end

#create(path) ⇒ Object

–}}}



494
495
496
497
498
499
500
501
502
503
504
505
506
# File 'lib/rq/lockfile.rb', line 494

def create path
#--{{{
  umask = nil 
  f = nil
  begin
    umask = File::umask 022
    f = open path, File::WRONLY|File::CREAT|File::EXCL, 0644
  ensure
    File::umask umask if umask
  end
  return(block_given? ? begin; yield f; ensure; f.close; end : f)
#--}}}
end

#create_tmplockObject

–}}}



428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
# File 'lib/rq/lockfile.rb', line 428

def create_tmplock
#--{{{
  tmplock = tmpnam @dirname
  begin
    create(tmplock) do |f|
      unless dont_use_lock_id
        @lock_id = gen_lock_id
        dumped = dump_lock_id
        trace{"lock_id <\n#{ @lock_id.inspect }\n>"}
        f.write dumped 
        f.flush
      end
      yield f
    end
  ensure
    begin; File::unlink tmplock; rescue Errno::ENOENT; end if tmplock
  end
#--}}}
end

#dump_lock_id(lock_id = @lock_id) ⇒ Object

–}}}



465
466
467
468
469
470
# File 'lib/rq/lockfile.rb', line 465

def dump_lock_id lock_id = @lock_id
#--{{{
  "host: %s\npid: %s\nppid: %s\ntime: %s\n" %
    lock_id.values_at('host','pid','ppid','time')
#--}}}
end

#errmsg(e) ⇒ Object

–}}}



531
532
533
534
535
# File 'lib/rq/lockfile.rb', line 531

def errmsg e
#--{{{
  "%s (%s)\n%s\n" % [e.class, e.message, e.backtrace.join("\n")]
#--}}}
end

#gen_lock_idObject

–}}}



447
448
449
450
451
452
453
454
455
456
# File 'lib/rq/lockfile.rb', line 447

def gen_lock_id
#--{{{
  Hash[
    'host' => "#{ HOSTNAME }",
    'pid' => "#{ Process.pid }",
    'ppid' => "#{ Process.ppid }",
    'time' => timestamp, 
  ]
#--}}}
end

#getopt(key, default = nil) ⇒ Object

–}}}



512
513
514
515
516
517
518
519
# File 'lib/rq/lockfile.rb', line 512

def getopt key, default = nil
#--{{{
  [ key, key.to_s, key.to_s.intern ].each do |k|
    return @opts[k] if @opts.has_key?(k)
  end
  return default
#--}}}
end

#give_up!Object



549
550
551
552
553
# File 'lib/rq/lockfile.rb', line 549

def give_up!
#----{{{
  throw 'attempt', 'give_up'
#----}}}
end

#load_lock_id(buf) ⇒ Object

–}}}



471
472
473
474
475
476
477
478
479
480
481
482
483
# File 'lib/rq/lockfile.rb', line 471

def load_lock_id buf 
#--{{{
  lock_id = {}
  kv = %r/([^:]+):(.*)/o
  buf.each do |line|
    m = kv.match line
    k, v = m[1], m[2]
    next unless m and k and v 
    lock_id[k.strip] = v.strip
  end
  lock_id
#--}}}
end

#lockObject

–}}}

Raises:



202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
# File 'lib/rq/lockfile.rb', line 202

def lock
#--{{{
  raise StackingLockError, "<#{ @path }> is locked!" if @locked

  sweep unless @dont_sweep

  ret = nil 

  attempt do
    begin
      @sleep_cycle.reset
      create_tmplock do |f|
        begin
          Timeout::timeout(@timeout) do
            tmp_path = f.path
            tmp_stat = f.lstat
            n_retries = 0
            trace{ "attempting to lock <#{ @path }>..." }
            begin
              i = 0
              begin
                trace{ "polling attempt <#{ i }>..." }
                begin
                  File::link tmp_path, @path
                rescue Errno::ENOENT
                  try_again!
                end
                lock_stat = File::lstat @path
                raise StatLockError, "stat's do not agree" unless
                  tmp_stat.rdev == lock_stat.rdev and tmp_stat.ino == lock_stat.ino 
                trace{ "aquired lock <#{ @path }>" }
                @locked = true
            rescue => e
              i += 1
              unless i >= @poll_retries 
                t = [rand(@poll_max_sleep), @poll_max_sleep].min
                trace{ "poll sleep <#{ t }>..." }
                sleep t
                retry
              end
              raise
            end

            rescue => e
              n_retries += 1
              trace{ "n_retries <#{ n_retries }>" }
              case validlock?
                when true
                  raise MaxTriesLockError, "surpased retries <#{ @retries }>" if 
                    @retries and n_retries >= @retries 
                  trace{ "found valid lock" }
                  sleeptime = @sleep_cycle.next 
                  trace{ "sleep <#{ sleeptime }>..." }
                  sleep sleeptime
                when false
                  trace{ "found invalid lock and removing" }
                  begin
                    File::unlink @path
                    @thief = true
                    warn "<#{ @path }> stolen by <#{ Process.pid }> at <#{ timestamp }>"
                    trace{ "i am a thief!" }
                  rescue Errno::ENOENT
                  end
                  trace{ "suspending <#{ @suspend }>" }
                  sleep @suspend
                when nil
                  raise MaxTriesLockError, "surpased retries <#{ @retries }>" if 
                    @retries and n_retries >= @retries 
              end
              retry
            end # begin
          end # timeout 
        rescue Timeout::Error
          raise TimeoutLockError, "surpassed timeout <#{ @timeout }>"
        end # begin
      end # create_tmplock

      if block_given?
        stolen = false
        refresher = (@refresh ? new_refresher : nil) 
        begin
          begin
            ret = yield @path
          rescue StolenLockError
            stolen = true
            raise
          end
        ensure
          begin
            refresher.kill if refresher and refresher.status
          ensure
            unlock unless stolen
          end
        end
      else
        ObjectSpace.define_finalizer self, @clean if @clean
        ret = self
      end
    rescue Errno::ESTALE, Errno::EIO => e
      raise(NFSLockError, errmsg(e)) 
    end
  end

  return ret
#--}}}
end

#new_refresherObject

–}}}



372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
# File 'lib/rq/lockfile.rb', line 372

def new_refresher
#--{{{
  Thread::new(Thread::current, @path, @refresh, @dont_use_lock_id) do |thread, path, refresh, dont_use_lock_id|
    loop do 
      begin
        touch path
        trace{"touched <#{ path }> @ <#{ Time.now.to_f }>"}
        unless dont_use_lock_id
          loaded = load_lock_id(IO.read(path))
          trace{"loaded <\n#{ loaded.inspect }\n>"}
          raise unless loaded == @lock_id 
        end
        sleep refresh
      rescue Exception => e
        trace{errmsg e}
        thread.raise StolenLockError
        Thread::exit
      end
    end
  end
#--}}}
end

#sweepObject

–}}}



308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
# File 'lib/rq/lockfile.rb', line 308

def sweep
#----{{{
  begin
    glob = File::join(@dirname, ".*lck")
    paths = Dir[glob]
    paths.each do |path|
      begin
        basename = File::basename path
        pat = %r/^\s*\.([^_]+)_([^_]+)/o
        if pat.match(basename)
          host, pid = $1, $2
        else
          next
        end
        host.gsub!(%r/^\.+|\.+$/,'')
        quad = host.split %r/\./
        host = quad.first
        pat = %r/^\s*#{ host }/i
        if pat.match(HOSTNAME) and %r/^\s*\d+\s*$/.match(pid)
          unless alive?(pid)
            trace{ "process <#{ pid }> on <#{ host }> is no longer alive" }
            trace{ "sweeping <#{ path }>" }
            FileUtils::rm_f path
          else
            trace{ "process <#{ pid }> on <#{ host }> is still alive" }
            trace{ "ignoring <#{ path }>" }
          end
        else
          trace{ "ignoring <#{ path }> generated by <#{ host }>" }
        end
      rescue
        next
      end
    end
  rescue => e
    warn(errmsg(e))
  end
#----}}}
end

#timestampObject

–}}}



457
458
459
460
461
462
463
464
# File 'lib/rq/lockfile.rb', line 457

def timestamp
#--{{{
  time = Time.now
  usec = time.usec.to_s
  usec << '0' while usec.size < 6
  "#{ time.strftime('%Y-%m-%d %H:%M:%S') }.#{ usec }"
#--}}}
end

#tmpnam(dir, seed = File::basename($0)) ⇒ Object

–}}}



484
485
486
487
488
489
490
491
492
493
# File 'lib/rq/lockfile.rb', line 484

def tmpnam dir, seed = File::basename($0)
#--{{{
  pid = Process.pid
  time = Time.now
  sec = time.to_i
  usec = time.usec
  "%s%s.%s_%d_%s_%d_%d_%d.lck" % 
    [dir, File::SEPARATOR, HOSTNAME, pid, seed, sec, usec, rand(sec)]
#--}}}
end

#to_strObject Also known as: to_s

–}}}



520
521
522
523
524
# File 'lib/rq/lockfile.rb', line 520

def to_str
#--{{{
  @path
#--}}}
end

#touch(path) ⇒ Object

–}}}



507
508
509
510
511
# File 'lib/rq/lockfile.rb', line 507

def touch path 
#--{{{
  FileUtils.touch path
#--}}}
end

#trace(s = nil) ⇒ Object



526
527
528
529
530
# File 'lib/rq/lockfile.rb', line 526

def trace s = nil 
#--{{{
  STDERR.puts((s ? s : yield)) if @debug
#--}}}
end

#try_again!Object Also known as: again!

—-}}}



543
544
545
546
547
# File 'lib/rq/lockfile.rb', line 543

def try_again!
#----{{{
  throw 'attempt', 'try_again'
#----}}}
end

#uncache(file) ⇒ Object

–}}}



409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
# File 'lib/rq/lockfile.rb', line 409

def uncache file 
#--{{{
  refresh = nil
  begin
    is_a_file = File === file
    path = (is_a_file ? file.path : file.to_s) 
    stat = (is_a_file ? file.stat : File::stat(file.to_s)) 
    refresh = tmpnam(File::dirname(path))
    File::link path, refresh
    File::chmod stat.mode, path
    File::utime stat.atime, stat.mtime, path
  ensure 
    begin
      File::unlink refresh if refresh
    rescue Errno::ENOENT
    end
  end
#--}}}
end

#unlockObject

—-}}}

Raises:



358
359
360
361
362
363
364
365
366
367
368
369
370
371
# File 'lib/rq/lockfile.rb', line 358

def unlock
#--{{{
  raise UnLockError, "<#{ @path }> is not locked!" unless @locked
  begin
    File::unlink @path
  rescue Errno::ENOENT
    raise StolenLockError, @path
  ensure
    @thief = false
    @locked = false
    ObjectSpace.undefine_finalizer self if @clean
  end
#--}}}
end

#validlock?Boolean

–}}}

Returns:

  • (Boolean)


394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
# File 'lib/rq/lockfile.rb', line 394

def validlock?
#--{{{
  if @max_age
    uncache @path rescue nil
    begin
      return((Time.now - File::stat(@path).mtime) < @max_age)
    rescue Errno::ENOENT
      return nil 
    end
  else
    exist = File::exist?(@path)
    return(exist ? true : nil)
  end
#--}}}
end

#versionObject



10
# File 'lib/rq/lockfile.rb', line 10

def version() VERSION end