From 2ff6774f8263409825c46bea6daa88ec511b96c1 Mon Sep 17 00:00:00 2001 From: MenTaLguY Date: Sun, 29 Jul 2007 16:49:10 -0400 Subject: [PATCH] more documentation --- lib/concurrent/primitives.rb | 8 ++ stubs/primitives.rb | 216 +++++++++++++++++++++++++++++++++++-------- 2 files changed, 188 insertions(+), 36 deletions(-) diff --git a/lib/concurrent/primitives.rb b/lib/concurrent/primitives.rb index 1bd32ce..84cae42 100644 --- a/lib/concurrent/primitives.rb +++ b/lib/concurrent/primitives.rb @@ -12,6 +12,14 @@ module Primitives require 'concurrent/primitives.so' class Semaphore + + # Executes the given block while the counter is decremented; will + # block if the count is currently zero. + # + # Can Block: Yes + # + # Scheduling: Unfair + # def with down begin diff --git a/stubs/primitives.rb b/stubs/primitives.rb index 856628f..f220603 100644 --- a/stubs/primitives.rb +++ b/stubs/primitives.rb @@ -1,56 +1,200 @@ module Concurrent module Primitives +# An asynchronous pi-calculus channel. Receivers wait for sent values to +# arrive, but senders do not wait for receivers. +# class Channel -def <<(value) -end - -def receive -end - -end - + # Sends a value on the channel and returns immediately. + # + # Can Block: Yes + # + # Scheduling: Unfair + def <<(value) + end + + # Receives a value from the channel, waiting if a value is not already + # available. + # + # Write Visibility: Writes made by the sending thread prior to sending + # become visible to the receiving thread + # + # Can Block: Yes + # + # Scheduling: Unfair + def receive + end + +end + +# A counting semaphore. +# +# Semaphores are often used to offer multiple threads access to a limited +# number of resources, represented by an internally-maintained counter. A +# thread calls Semaphore#down to reserve a resource, decrementing the counter, +# and returns the resource to the pool by calling Semaphore#up. +# +# A semaphore whose initial count is one, and whose count never exceeds one, +# is essentially a mutex. +# +# An alternate way of looking at a semaphore is as an asynchronous channel +# where the values written are ignored. In principle, a semaphore could +# be implemented like this, where the current count is represented by the +# number of queued writes: +# +# class Semaphore +# def initialize(initial_count=0) +# @channel = Channel.new +# initial_count.times { @channel } +# end +# +# def down +# @channel.receive +# self +# end +# +# def up +# @channel << nil +# self +# end +# end +# class Semaphore def initialize(initial_count=0) end -def with -end - -end - + # Increments the semaphore's count and returns immediately. + # + # Can Block: Yes + # + # Scheduling: Unfair + # + def up + end + + # Decrements the semaphore's count, or blocks and waits for it to be + # incremented if the count is currently zero. + # + # Write Visibility: Writes made by the incrementing thread prior + # to incrementing are made visible to the decrementing thread. + # + # Can Block: Yes + # + # Scheduling: Unfair + # + def down + end +end + +# A single-shot latch. +# +# Threads calling Latch#wait will block until Latch#set is called, after +# which all calls to Latch#wait will return immediately. Provides a +# race-free way to wait for simple conditions. +# class Latch -def set -end - -def clear -end - -end - + # Sets the latch, unblocking any currently waiting threads. + # + # Can Block: Yes + # + # Scheduling: Unfair + # + def set + end + + # Waits for the latch to be set, or returns immediately if it is already + # set. + # + # Can Block: Yes + # + # Scheduling: Unfair + # + def wait + end + +end + +# Volatile provides a single cell which may be updated without blocking; +# new values are immediately visible to all threads. +# class Volatile -attr_accessor :value - -def initialize(initial_value=nil) -end - -end - + # Creates a new cell, initialized to +initial_value+ + def initialize(initial_value=nil) + end + + # Returns the current value of the cell. + # + # Write visibility: writes made by any writing thread are available + # to the reading thread + # + # Can Block: No + # + def value + end + + # Sets the cell to +value+, returning +value+. + # + # Write visibility: writes up to and including this write are made + # available to all reading threads + # + # Can Block: No + # + def value=(value) + end + +end + +# Atomic is similar to Volatile, except that it also offers atomic swap +# and compare-and-set operations. +# class Atomic -attr_accessor :value - -def initialize(initial_value=nil) -end - -def swap(value) -end + # Creates a new cell, initialized to +initial_value+. + # + def initialize(initial_value=nil) + end + + # Returns the current value of the cell. + # + # Write visibility: writes made by any writing thread are available + # to the reading thread + # + # Can Block: No + # + def value + end + + # Sets the cell to +value+, returning +value+. + # + # Write visibility: writes up to and including this write are made + # available to all reading threads + # + # Can Block: No + # + def value=(value) + end + + # Similar to Atomic#value=, but exchanges the old and new values + # atomically and returns the old value. + # + # Can Block: No + # + def swap(value) + end + + # Atomically replaces the stored value with the given +value+, provided + # that the existing value is equal to +expected+. Returns true on success, + # false otherwise. + # + # Can Block: No + # + def set_if_equal(expected, value) + end -def set_if_equal(expected, value) end end -- 2.11.4.GIT