# module MonitorMixin

In concurrent programming, a monitor is an object or module intended to be used safely by more than one thread. The defining characteristic of a monitor is that its methods are executed with mutual exclusion. That is, at each point in time, at most one thread may be executing any of its methods. This mutual exclusion greatly simplifies reasoning about the implementation of monitors compared to reasoning about parallel code that updates a data structure.

You can read more about the general principles on the Wikipedia page for Monitors.

## Examples¶ ↑

### Simple object.extend¶ ↑

    require 'monitor.rb'

    buf = []
    buf.extend(MonitorMixin)
    empty_cond = buf.new_cond

    # consumer
    Thread.start do
      loop do
        buf.synchronize do
          empty_cond.wait_while { buf.empty? }
          print buf.shift
        end
      end
    end

    # producer
    while line = ARGF.gets
      buf.synchronize do
        buf.push(line)
        empty_cond.signal
      end
    end

The consumer thread waits for the producer thread to push a line to buf while `buf.empty?`. The producer thread (main thread) reads a line from `ARGF` and pushes it into buf then calls `empty_cond.signal` to notify the consumer thread of new data.

### Simple `Class` include¶ ↑

    require 'monitor'

    class SynchronizedArray < Array

      include MonitorMixin

      def initialize(*args)
        super(*args)
      end

      alias :old_shift :shift
      alias :old_unshift :unshift

      def shift(n=1)
        self.synchronize do
          self.old_shift(n)
        end
      end

      def unshift(item)
        self.synchronize do
          self.old_unshift(item)
        end
      end

      # other methods ...
    end

`SynchronizedArray` implements an `Array` with synchronized access to items. This `Class` is implemented as subclass of `Array` which includes the `MonitorMixin` module.

### Public Class Methods

new (...)
Source

    # File ext/monitor/lib/monitor.rb, line 222
    def initialize(...)
      super
      mon_initialize
    end

Use `extend MonitorMixin` or `include MonitorMixin` instead of this constructor. Have look at the examples above to understand how to use this module.

Calls superclass method

### Public Instance Methods

mon_enter ()
Source

    # File ext/monitor/lib/monitor.rb, line 169
    def mon_enter
      @mon_data.enter
    end

Enters exclusive section.

mon_exit ()
Source

    # File ext/monitor/lib/monitor.rb, line 176
    def mon_exit
      mon_check_owner
      @mon_data.exit
    end

Leaves exclusive section.

mon_locked? ()
Source

    # File ext/monitor/lib/monitor.rb, line 184
    def mon_locked?
      @mon_data.mon_locked?
    end

Returns true if this monitor is locked by any thread

mon_owned? ()
Source

    # File ext/monitor/lib/monitor.rb, line 191
    def mon_owned?
      @mon_data.mon_owned?
    end

Returns true if this monitor is locked by current thread.

mon_synchronize (&b)
Source

    # File ext/monitor/lib/monitor.rb, line 200
    def mon_synchronize(&b)
      @mon_data.synchronize(&b)
    end

Enters exclusive section and executes the block. Leaves the exclusive section automatically when the block exits. See example under `MonitorMixin`.

Also aliased as: synchronize
mon_try_enter ()
Source

    # File ext/monitor/lib/monitor.rb, line 160
    def mon_try_enter
      @mon_data.try_enter
    end

Attempts to enter exclusive section. Returns `false` if lock fails.

Also aliased as: try_mon_enter
new_cond ()
Source

    # File ext/monitor/lib/monitor.rb, line 209
    def new_cond
      unless defined?(@mon_data)
        mon_initialize
        @mon_initialized_by_new_cond = true
      end
      return ConditionVariable.new(@mon_data)
    end

Creates a new `MonitorMixin::ConditionVariable` associated with the `Monitor` object.

synchronize (&b)
Alias for: mon_synchronize
try_mon_enter ()

For backward compatibility

Alias for: mon_try_enter

### Private Instance Methods

mon_check_owner ()
Source

    # File ext/monitor/lib/monitor.rb, line 243
    def mon_check_owner
      @mon_data.mon_check_owner
    end

Ensures that the `MonitorMixin` is owned by the current thread, otherwise raises an exception.

mon_initialize ()
Source

    # File ext/monitor/lib/monitor.rb, line 229
    def mon_initialize
      if defined?(@mon_data)
        if defined?(@mon_initialized_by_new_cond)
          return # already initialized.
        elsif @mon_data_owner_object_id == self.object_id
          raise ThreadError, "already initialized"
        end
      end
      @mon_data = ::Monitor.new
      @mon_data_owner_object_id = self.object_id
    end

Initializes the `MonitorMixin` after being included in a class or when an object has been extended with the `MonitorMixin`