Class: Win32::Mutex

Inherits:
Ipc
  • Object
show all
Defined in:
lib/win32/mutex.rb

Overview

The Mutex class encapsulates Windows mutex objects.

Defined Under Namespace

Classes: SecurityAttributes

Constant Summary collapse

VERSION =

The version of the win32-mutex library

'0.4.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(initial_owner = false, name = nil, inherit = true) ⇒ Mutex

Creates and returns new Mutex object. If name is omitted, the Mutex object is created without a name, i.e. it’s anonymous.

If the initial_owner value is true and the caller created the mutex, the calling thread obtains initial ownership of the mutex object. Otherwise, the calling thread does not obtain ownership of the mutex. This value is false by default.

If name is provided and it already exists, then it is opened instead, and the initial_count and max_count parameters are ignored.

The inherit attribute determines whether or not the mutex can be inherited by child processes.



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
 
# File 'lib/win32/mutex.rb', line 52

def initialize(initial_owner=false, name=nil, inherit=true)
  @initial_owner = initial_owner
  @name          = name
  @inherit       = inherit

  if inherit
    sec = SecurityAttributes.new
    sec[:nLength] = SecurityAttributes.size
    sec[:bInheritHandle] = true
  else
    sec = nil
  end

  if name && name.encoding.to_s != 'UTF-16LE'
    name = name + 0.chr
    name.encode!('UTF-16LE')
  end

  handle = CreateMutexW(sec, initial_owner, name)

  if handle == 0 || handle == INVALID_HANDLE_VALUE
    raise SystemCallError.new("CreateMutex", FFI.errno)
  end

  super(handle)

  if block_given?
    begin
      yield self
    ensure
      close # From superclass
    end
  end
end

Instance Attribute Details

#name ⇒ Object (readonly)

The name of the mutex object.



35
36
37
 
# File 'lib/win32/mutex.rb', line 35

def name
  @name
end

Class Method Details

.open(name, inherit = true, &block) ⇒ Object

Open an existing Mutex by name. The inherit argument sets whether or not the object was opened such that a process created by the CreateProcess() function (a Windows API function) can inherit the handle. The default is true.

This method is essentially identical to Mutex.new, except that the option for initial_owner cannot be set (since it is already set). Also, this method will raise a Mutex::Error if the mutex doesn’t already exist.

If you want “open or create” semantics, then use Mutex.new.



99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/win32/mutex.rb', line 99

def self.open(name, inherit=true, &block)
  if name.encoding.to_s != 'UTF-16LE'
    name = name + 0.chr
    name.encode!('UTF-16LE')
  end

  begin
    # The OpenMutex() call here is strictly to force an error if the user
    # tries to open a mutex that doesn't already exist.
    handle = OpenMutexW(MUTEX_ALL_ACCESS, inherit, name)

    if handle == 0 || handle == INVALID_HANDLE_VALUE
      raise SystemCallError.new("OpenMutex", FFI.errno)
    end
  ensure
    CloseHandle(handle) if handle && handle > 0
  end

  self.new(false, name, inherit, &block)
end

Instance Method Details

#inheritable? ⇒ Boolean

Returns whether or not the object was opened such that a process created by the CreateProcess() function (a Windows API function) can inherit the handle. The default is true.

Returns:

  • (Boolean) 


139
140
141
 
# File 'lib/win32/mutex.rb', line 139

def inheritable?
  @inherit
end

#initial_owner? ⇒ Boolean

Returns whether or not the calling thread has initial ownership of the mutex object.

Returns:

  • (Boolean) 


131
132
133
 
# File 'lib/win32/mutex.rb', line 131

def initial_owner?
  @initial_owner
end

#release ⇒ Object

Releases ownership of the mutex.



122
123
124
125
126
 
# File 'lib/win32/mutex.rb', line 122

def release
  unless ReleaseMutex(@handle)
    raise SystemCallError.new("ReleaseMutex", FFI.errno)
  end
end