Class: LockFile

Inherits:
Object
  • Object
show all
Defined in:
lib/lockf.rb,
lib/lockf/version.rb

Overview

The LockFile class provides a Ruby interface to lockf(3).

Constant Summary collapse

VERSION = 
"1.0.0"

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file, len = 0) ⇒ LockFile

Returns an instance of LockFile.

Parameters:

  • file (<File, TempFile, String, #fileno>) —

    The file to place a lock on.

  • len (Integer) (defaults to: 0) —

    The number of bytes to place a lock on. A value of "0" covers the entire file.



76
77
78
79
 
# File 'lib/lockf.rb', line 76

def initialize(file, len = 0)
  @file = String === file ? File.open(file, "r+") : file
  @len = len
end

Instance Attribute Details

#file ⇒ <File, Tempfile, #fileno> (readonly)

Returns a file object.

Returns:

  • (<File, Tempfile, #fileno>) —

    Returns a file object.



64
65
66
 
# File 'lib/lockf.rb', line 64

def file
  @file
end

Class Method Details

.from_temporary_file(basename: "lockf", tmpdir: Dir.tmpdir) ⇒ LockFile Also known as: temporary_file

Returns an instance of LockFile backed by an unlinked instance of Tempfile.

Examples:

lockf = LockFile.temporary_file
lockf.lock
lockf.release
lockf.file.close

Parameters:

  • basename (String) (defaults to: "lockf") —

    The basename of the temporary file.

  • tmpdir (String) (defaults to: Dir.tmpdir) —

    The path to the parent directory of the temporary file.

Returns:

  • (LockFile) —

    Returns an instance of LockFile backed by an unlinked instance of Tempfile.



52
53
54
55
56
 
# File 'lib/lockf.rb', line 52

def self.from_temporary_file(basename: "lockf", tmpdir: Dir.tmpdir)
  require "tempfile" unless defined?(Tempfile)
  file = Tempfile.new(basename, tmpdir:).tap(&:unlink)
  LockFile.new(file)
end

.lockf(fd, cmd, len) ⇒ Integer

Returns 0 on success.

Examples:

LockFile.lockf(5, LockFile::F_LOCK, 0)

Parameters:

  • fd (Integer) —

    A number that represents a file descriptor.

  • cmd (Integer) —

    F_LOCK, F_TLOCK, F_ULOCK, or F_TEST.

  • len (Integer) —

    The number of bytes to place a lock on. A value of "0" covers the entire file.

Returns:

  • (Integer) —

    Returns 0 on success.

Raises:

  • (SystemCallError) —

    Might raise a number of Errno exception classes.

See Also:




# File 'lib/lockf.rb', line 10

Instance Method Details

#close ⇒ void

This method returns an undefined value.

Closes LockFile#file.

Examples:

# Equivalent to:
lockf = LockFile.temporary_file
lockf.file.close


138
139
140
141
 
# File 'lib/lockf.rb', line 138

def close
  return unless @file.respond_to?(:close)
  @file.close
end

#lock ⇒ Integer

Acquire a lock (blocking).

Returns:

  • (Integer)

Raises:

  • (Errno::EBADF)
  • (Errno::EDEADLK)
  • (Errno::EINTR)
  • (Errno::ENOLCK) 


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

def lock
  attempts ||= 0
  LockFile.lockf(@file.fileno, F_LOCK, @len)
rescue Errno::EINTR => ex
  attempts += 1
  attempts == 3 ? raise(ex) : retry
end

#lock_nonblock ⇒ Integer

Acquire a lock (non-blocking).

Returns:

  • (Integer)

Raises:

  • (Errno::EAGAIN)
  • (Errno::EBADF)
  • (Errno::ENOLCK)
  • (Errno::EINVAL) 


105
106
107
 
# File 'lib/lockf.rb', line 105

def lock_nonblock
  LockFile.lockf(@file.fileno, F_TLOCK, @len)
end

#release ⇒ Integer

Release a lock.

Returns:

  • (Integer)

Raises:

  • (Errno::EBADF)
  • (Errno::ENOLCK) 


115
116
117
 
# File 'lib/lockf.rb', line 115

def release
  LockFile.lockf(@file.fileno, F_ULOCK, @len)
end

#locked? ⇒ Boolean

Returns true when a lock has been acquired by another process.

Returns:

  • (Boolean) —

    Returns true when a lock has been acquired by another process.



122
123
124
125
126
127
 
# File 'lib/lockf.rb', line 122

def locked?
  LockFile.lockf(@file.fileno, F_TEST, @len)
  false
rescue Errno::EACCES, Errno::EAGAIN
  true
end