threads documentation

Rev: doc/builtin/thread_create:1.1
Rev: doc/precompiled/condition:1.1
Rev: doc/precompiled/mutex:1.1

doc/builtin/thread_create

+NAME
+	thread_create - create a thread
+
+SYNTAX
+	int thread_create(function f, mixed ... args);
+
+DESCRIPTION
+	This function creates a new thread which will run simultaneously
+	to the rest of the program. The new thread will call the function
+	f with the arguments args. When f returns the thread will cease
+	to exist. All Pike functions are 'thread safe' meanting that running
+	a function at the same time from different threads will not corrupt
+	any internal data in the Pike process.
+
+NOTA BENE
+	This function is only available on systems with POSIX threads support.
+
+SEE ALSO
+	/precompiled/mutex, /precompiled/condition
\ No newline at end of file

doc/precompiled/condition

+NAME
+	/precompiled/condition - condition variables
+
+DESCRIPTION
+	/precompiled/condition is a precompiled Pike program that implements
+	condition variables. Condition variables are used by threaded programs
+	to wait for events happening in other threads.
+
+NOTA BENE
+	Mutex locks are only available on systems with POSIX threads support.
+
+EXAMPLE
+	// This program implements a fifo that can be used to send
+	// data between two threads.
+	inherit "/precompiled/condition": r_cond;
+	inherit "/precompiled/condition": w_cond;
+	inherit "/precompiled/mutex": lock;
+
+	mixed *buffer = allocate(128);
+	int r_ptr, w_ptr;
+
+	int query_messages()    {  return w_ptr - r_ptr;  }
+
+	// This function reads one mixed value from the fifo.
+	// If no values are available it blocks until a write has been done.
+	mixed read()
+	{
+	  mixed tmp;
+	  // We use this mutex lock to make sure no write() is executed
+	  // between the query_messages and the wait() call. If it did
+	  // we would wind up in a deadlock.
+	  object key=lock::lock();
+	  while(!query_messages()) r_cond::wait(key);
+	  tmp=buffer[r_ptr++ % sizeof(buffer)];
+	  w_cond::signal();
+	  return tmp;
+	}
+
+	// This function pushes one mixed value on the fifo.
+	// If the fifo is full it blocks until a value has been read.
+	void write(mixed v)
+	{
+	  object key=lock::lock();
+	  while(query_messages() == sizeof(buffer)) w_cond::wait(key);
+	  buffer[w_ptr++ % sizeof(buffer)]=v;
+	  r_cond::signal();
+	}
+
+SEE ALSO
+	/precompiled/mutex
+
+============================================================================
+NAME
+	wait - wait for condition
+
+SYNTAX
+	void condition->wait();
+	or
+	void condition->wait(object mutex_key);
+
+DESCRIPTION
+	This function makes the current thread sleep until the condition
+	variable is signalled. The optional argument should be the 'key'
+	to a mutex lock. If present the mutex lock will be unlocked before
+	waiting for the condition in one atomical operation. After waiting
+	for the condition the mutex referenced by mutex_key will be re-locked.
+
+SEE ALSO
+	mutex->lock
+
+============================================================================
+NAME
+	signal - signal a condition variable
+
+SYNTAX
+	void condition->signal();
+
+DESCRIPTION
+	Signal wakes up one of the threads currently waiting for the
+	condition.
+
+BUGS
+	It sometimes wakes up more than one thread.
+
+============================================================================
+NAME
+	broadcast - signal all waiting threads
+
+SYNTAX
+	void condition->broadcast();
+
+DESCRIPTION
+	This function wakes up all threads currently waiting for this
+	condition.
+
+============================================================================

doc/precompiled/mutex

+NAME
+	/precompiled/mutex - mutex locks
+
+DESCRIPTION
+	/precompiled/mutex is a precompiled Pike program that implements
+	mutal exclusion locks. Mutex locks are used to prevent multiple
+	threads from simultaneously execute sections of code which accesses
+	or changes shared data. The basic operations for a mutex is locking
+	and unlocking, if a thread attempts to lock an already locked mutex
+	the thread will sleep until the mutex is unlocked.
+
+NOTA BENE
+	Mutex locks are only available on systems with POSIX threads support.
+
+============================================================================
+NAME
+	lock - lock the mutex
+
+SYNTAX
+	object mutex->lock();
+
+DESCRIPTION
+	This function attempts to lock the mutex, if the mutex is already
+	locked current thread will sleep until the lock is unlocked by some
+	other thread. The value returned is the 'key' to the lock, which the
+	key is destructed or has no more references the lock will automatically
+	be unlocked.
+
+============================================================================
+NAME
+	trylock - try to lock the mutex
+
+SYNTAX
+	object mutex->trylock();
+
+DESCRIPTION
+	This function preforms the same operation as lock(), but if the mutex
+	is already locked zero will be returned instead of sleeping until the
+	lock is unlocked.
+
+============================================================================