# The Thread Library

The `Thread` library allows concurrent programming in Ruby. It provides multiple threads of control that execute concurrently sharing same memory space. The Ruby interpreter executes threads by time-sharing, therefore using threads never makes program run faster (even much slower for the cost of context switching).

The thread which created first when the Ruby process started, is called the main thread. When the main thread is terminated for some reason, all other threads will be terminated, and the whole process will be terminated. The exception raised by the user interrupt is delivered to the main thread.

The `Thread` library is optional, and may not be available on some Ruby interpreter, which thread feature is disabled by the compile time configuration.

# Thread

  The `Thread` class represents user-level threads.

  Threads terminates when the execution of the given iterater block returns, normally or by raisung an exception.

## SuperClass:

  Object

## Class Methods:

  `abort_on_exception`

    Returns the value of the abort flag.

  `abort_on_exception=(yes_no)`

    Sets the value of the flag to abort the interpreter if any unhandled exception terminates any thread.

  `current`

    Returns the current thread object which calls the method.

  `exit`

    Terminates the current thread.

  `kill(thread)`

    Terminates the specified thread.

  `new {...}`
  `start {...}`
  `fork {...}`

    Creates a new thread of contorl, then starts evaluating the block concurrently. Returns a newly created thread object.

  `pass`

    Gives other runnable threads chance to run.

  `stop`

    Suspends the current thread until another thread resumes it using `run` method.

## Methods:

  `self[name]`

    Retrieves thread local data associated with name. The name is either string or symbol.

  `self[name]=val`

    Stores val into the thread local dictionary, associating with name. The name is either string or symbol.

  `abort_on_exception`

    Returns the value of the abort flag of the thread.

  `abort_on_exception=(yes_no)`

    Sets the value of the flag to abort the interpreter if any unhandled exception terminates the thread.

  `alive?`
  `status`

    Returns `true` if the thread is alive. Returns `false` for normal termination, `nil` for termination by exception.

  `exit`

    Terminates the thread.

  `join`

    Suspends the current thread until the thread has terminated.

  `raise([error_type,][message][,traceback])`

    Raises an exception on the thread.

  `run`

    Resumes the thread. It does nothing if the thread was not suspended.

  `stop?`

    Returns true if the thread is stopped.

  `value`

    Waits for the thread to terminate and returns the evaluated value of the block, which is given to the `Thread.create`.

  `wakeup`

    Resumes the thread.

# Mutex

  Mutexs (mutual-exclusion locks) are used to protect shared data against concurrent accesses. The typical use is (where `m` is the mutex object):

  >     begin
  >       m.lock
  >       # critical section protected by m
  >     ensure
  >       m.unlock
  >     end

  or, in short

  >     m.synchronize {
  >       # critical section protected by m
  >     }

## SuperClass:

  Object

## Class Methods:

  `new`

    Creates a new `Mutex` object.

## Methods:

  `lock`

    Locks the mutex object. Only on thread at a time can lock the mutex. A thread that attempts to lock a alread locked mutex will suspend until the other thread unlocks the mutex.

  `locked?`

    Returns true if the mutex is locked.

  `synchronize`

    Locks the mutex, and evaluates the block. Ensures the mutex be unlocked.

  `try_lock`

    Locks the mutex and returns true if the mutex is not locked. If the mutex is already locked, just returns false.

  `unlock`

    Unlocks the mutex. Other thread suspended trying to lock the mutex will be resumed.

# Queue

  The `Queue` is the FIFO (first in first out) communication channel between threads. If a thread trys to read an empty queue, it will be suspended until the queue is filled.

## SuperClass:

  Object

## Class Methods:

  `new`

    Creates a new queue object.

## Methods:

  `empty?`

    Returns true if the queue is empty.

  `length`

    Returns the length of the queue.

  `pop [non_block]`

    Removes and returns an value from queue. If the queue is empty, the calling thread will be suspended until some value pushed in the queue. If optional argument non_block is non-nil, `pop` raises an exception if no value available in the queue.

  `push(value)`

    Append an value to the queue. Restart the waiting thread if any.

up - next - index

matz@netlab.co.jp