Class: Win32::Mutex

Inherits:
Ipc
  • Object
show all
Extended by:
Windows::Error, Windows::Handle, Windows::Synchronize
Defined in:
lib/win32/mutex.rb

Overview

The Mutex class encapsulates Windows mutex objects.

Defined Under Namespace

Classes: Error

Constant Summary collapse

VERSION =

The version of the win32-mutex library

'0.3.2'

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.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/win32/mutex.rb', line 37

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

   # Used to prevent potential segfaults.
   if name && !name.is_a?(String)
      raise TypeError, 'name must be a string'
   end

   if inherit
      sec = 0.chr * 12 # sizeof(SECURITY_ATTRIBUTES)
      sec[0,4] = [12].pack('L')
      sec[8,4] = [1].pack('L') # 1 == TRUE
   else
      sec = 0
   end

   initial = initial_owner ? 1 : 0

   handle = CreateMutex(sec, initial, name)

   if handle == 0 || handle == INVALID_HANDLE_VALUE
      raise Error, get_last_error
   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.



20
21
22
 
# File 'lib/win32/mutex.rb', line 20

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.



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/win32/mutex.rb', line 86

def self.open(name, inherit=true, &block)
   if name && !name.is_a?(String)
      raise TypeError, 'name must be a string'
   end

   bool = inherit ? 1 : 0

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

      if handle == 0 || handle == INVALID_HANDLE_VALUE
         raise Error, get_last_error
      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) 


127
128
129
 
# File 'lib/win32/mutex.rb', line 127

def inheritable?
   @inherit
end

#initial_owner? ⇒ Boolean

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

Returns:

  • (Boolean) 


119
120
121
 
# File 'lib/win32/mutex.rb', line 119

def initial_owner?
   @initial_owner
end

#release ⇒ Object

Releases ownership of the mutex.



110
111
112
113
114
 
# File 'lib/win32/mutex.rb', line 110

def release
   unless ReleaseMutex(@handle)
      raise Error, get_last_error
   end
end