Class: Mutex

Inherits:

Object

• Object
• Mutex

Defined in:

thread.c,
thread.c

Overview

Mutex implements a simple semaphore that can be used to coordinate access to shared data from multiple concurrent threads.

Example:

require 'thread'
semaphore = Mutex.new

a = Thread.new {
  semaphore.synchronize {
    # access shared resource
  }
}

b = Thread.new {
  semaphore.synchronize {
    # access shared resource
  }
}

Instance Method Summary

• #new ⇒ Object constructor

  Creates a new Mutex.

• #lock ⇒ self

  Attempts to grab the lock and waits if it isn't available.

• #locked? ⇒ Boolean

  Returns true if this lock is currently held by some thread.

• #owned? ⇒ Boolean

  Returns true if this lock is currently held by current thread.

• #sleep(timeout = nil) ⇒ Numeric

  Releases the lock and sleeps timeout seconds if it is given and non-nil or forever.

• #synchronize { ... } ⇒ Object

  Obtains a lock, runs the block, and releases the lock when the block completes.

• #try_lock ⇒ Boolean

  Attempts to obtain the lock and returns immediately.

• #unlock ⇒ self

  Releases the lock.

Constructor Details

#new ⇒ Object

Creates a new Mutex

# File 'thread.c', line 4111

static VALUE
mutex_initialize(VALUE self)
{
    return self;
}

Instance Method Details

#lock ⇒ self

Attempts to grab the lock and waits if it isn't available. Raises ThreadError if mutex was locked by the current thread.

Returns:

• (self)

# File 'thread.c', line 4239

VALUE
rb_mutex_lock(VALUE self)
{
    rb_thread_t *th = GET_THREAD();
    rb_mutex_t *mutex;
    GetMutexPtr(self, mutex);

    /* When running trap handler */
    if (!mutex->allow_trap && th->interrupt_mask & TRAP_INTERRUPT_MASK) {
	rb_raise(rb_eThreadError, "can't be called from trap context");
    }

    if (rb_mutex_trylock(self) == Qfalse) {
	if (mutex->th == GET_THREAD()) {
	    rb_raise(rb_eThreadError, "deadlock; recursive locking");
	}

	while (mutex->th != th) {
	    int interrupted;
	    enum rb_thread_status prev_status = th->status;
	    volatile int timeout_ms = 0;
	    struct rb_unblock_callback oldubf;

	    set_unblock_function(th, lock_interrupt, mutex, &oldubf, FALSE);
	    th->status = THREAD_STOPPED_FOREVER;
	    th->locking_mutex = self;

	    native_mutex_lock(&mutex->lock);
	    th->vm->sleeper++;
	    /*
	     * Carefully! while some contended threads are in lock_func(),
	     * vm->sleepr is unstable value. we have to avoid both deadlock
	     * and busy loop.
	     */
	    if ((vm_living_thread_num(th->vm) == th->vm->sleeper) &&
		!patrol_thread) {
		timeout_ms = 100;
		patrol_thread = th;
	    }

	    GVL_UNLOCK_BEGIN();
	    interrupted = lock_func(th, mutex, (int)timeout_ms);
	    native_mutex_unlock(&mutex->lock);
	    GVL_UNLOCK_END();

	    if (patrol_thread == th)
		patrol_thread = NULL;

	    reset_unblock_function(th, &oldubf);

	    th->locking_mutex = Qfalse;
	    if (mutex->th && interrupted == 2) {
		rb_check_deadlock(th->vm);
	    }
	    if (th->status == THREAD_STOPPED_FOREVER) {
		th->status = prev_status;
	    }
	    th->vm->sleeper--;

	    if (mutex->th == th) mutex_locked(th, self);

	    if (interrupted) {
		RUBY_VM_CHECK_INTS_BLOCKING(th);
	    }
	}
    }
    return self;
}

#locked? ⇒ Boolean

Returns true if this lock is currently held by some thread.

Returns:

• (Boolean)

Returns:

• (Boolean)

# File 'thread.c', line 4129

VALUE
rb_mutex_locked_p(VALUE self)
{
    rb_mutex_t *mutex;
    GetMutexPtr(self, mutex);
    return mutex->th ? Qtrue : Qfalse;
}

#owned? ⇒ Boolean

Returns true if this lock is currently held by current thread. This API is experimental, and subject to change.

Returns:

• (Boolean)

Returns:

• (Boolean)

# File 'thread.c', line 4315

VALUE
rb_mutex_owned_p(VALUE self)
{
    VALUE owned = Qfalse;
    rb_thread_t *th = GET_THREAD();
    rb_mutex_t *mutex;

    GetMutexPtr(self, mutex);

    if (mutex->th == th)
	owned = Qtrue;

    return owned;
}

#sleep(timeout = nil) ⇒ Numeric

Releases the lock and sleeps timeout seconds if it is given and non-nil or forever. Raises ThreadError if mutex wasn't locked by the current thread.

Note that this method can wakeup without explicit Thread#wakeup call. For example, receiving signal and so on.

Returns:

• (Numeric)

# File 'thread.c', line 4448

static VALUE
mutex_sleep(int argc, VALUE *argv, VALUE self)
{
    VALUE timeout;

    rb_scan_args(argc, argv, "01", &timeout);
    return rb_mutex_sleep(self, timeout);
}

#synchronize { ... } ⇒ Object

Obtains a lock, runs the block, and releases the lock when the block completes. See the example under Mutex.

Yields:

# File 'thread.c', line 4479

static VALUE
rb_mutex_synchronize_m(VALUE self, VALUE args)
{
    if (!rb_block_given_p()) {
	rb_raise(rb_eThreadError, "must be called with a block");
    }

    return rb_mutex_synchronize(self, rb_yield, Qnil);
}

#try_lock ⇒ Boolean

Attempts to obtain the lock and returns immediately. Returns true if the lock was granted.

Returns:

• (Boolean)

# File 'thread.c', line 4156

VALUE
rb_mutex_trylock(VALUE self)
{
    rb_mutex_t *mutex;
    VALUE locked = Qfalse;
    GetMutexPtr(self, mutex);

    native_mutex_lock(&mutex->lock);
    if (mutex->th == 0) {
	mutex->th = GET_THREAD();
	locked = Qtrue;

	mutex_locked(GET_THREAD(), self);
    }
    native_mutex_unlock(&mutex->lock);

    return locked;
}

#unlock ⇒ self

Releases the lock. Raises ThreadError if mutex wasn't locked by the current thread.

Returns:

• (self)

# File 'thread.c', line 4370

VALUE
rb_mutex_unlock(VALUE self)
{
    const char *err;
    rb_mutex_t *mutex;
    GetMutexPtr(self, mutex);

    /* When running trap handler */
    if (!mutex->allow_trap && GET_THREAD()->interrupt_mask & TRAP_INTERRUPT_MASK) {
	rb_raise(rb_eThreadError, "can't be called from trap context");
    }

    err = rb_mutex_unlock_th(mutex, GET_THREAD());
    if (err) rb_raise(rb_eThreadError, "%s", err);

    return self;
}