~drizzle-trunk/drizzle/development : contents of docs/barriers.rst at revision 1994.4.81

~drizzle-trunk/drizzle/development : (revision 1994.4.81)

User Defined Barriers
=====================

SELECT create_barrier();

SELECT release_barrier();

SELECT wait();

SELECT wait_until();

SELECT signal();

A barrier is a synchronization object which can be used to synchronize a group of sessions to a specific rendezvous by calling wait(). When wait() is called, any session of the user may call signal(), allowing all sessions being held by wait() to proceed.

Barriers can optionally be created with a limit so that once a set number of sessions have called wait() that all "waiters" are then allowed to proceed. 

The session that creates the barrier via create_barrier() is not allowed to call either wait() or wait_until().

The scope of barriers is to the given username.

Beyond waiters, you can also create observers by using the wait_until() function. Observers are released not only when signal() or release_barrier() is called, but also when their definitive predicate happens. You can use wait_until() to have a session wait for a certain number of waiters to occur, and then do some body of work before the waiters() are signaled to continue.

All waiters and observers are released if release_barrier() is called by the session which created the barrier. Also, if the session that created the barrier disconnects, all waiters and observers are notified.

Information on all barriers can be found in the DATA_DICTIONARY.USER_BARRIERS table.


1933.1.9 by Brian Aker Additional documentation and testing.	1	User Defined Barriers
	2	=====================
	3
	4	SELECT create_barrier();
	5
	6	SELECT release_barrier();
	7
	8	SELECT wait();
	9
	10	SELECT wait_until();
	11
	12	SELECT signal();
	13
1994.4.69 by Marisa Plumb edits and more conditional functions	14	A barrier is a synchronization object which can be used to synchronize a group of sessions to a specific rendezvous by calling wait(). When wait() is called, any session of the user may call signal(), allowing all sessions being held by wait() to proceed.
1933.1.9 by Brian Aker Additional documentation and testing.	15
1945.3.5 by Marisa Plumb more sql doc modifications	16	Barriers can optionally be created with a limit so that once a set number of sessions have called wait() that all "waiters" are then allowed to proceed.
1933.1.9 by Brian Aker Additional documentation and testing.	17
1994.4.69 by Marisa Plumb edits and more conditional functions	18	The session that creates the barrier via create_barrier() is not allowed to call either wait() or wait_until().
1933.1.9 by Brian Aker Additional documentation and testing.	19
	20	The scope of barriers is to the given username.
	21
1994.4.69 by Marisa Plumb edits and more conditional functions	22	Beyond waiters, you can also create observers by using the wait_until() function. Observers are released not only when signal() or release_barrier() is called, but also when their definitive predicate happens. You can use wait_until() to have a session wait for a certain number of waiters to occur, and then do some body of work before the waiters() are signaled to continue.
	23
	24	All waiters and observers are released if release_barrier() is called by the session which created the barrier. Also, if the session that created the barrier disconnects, all waiters and observers are notified.
	25
	26	Information on all barriers can be found in the DATA_DICTIONARY.USER_BARRIERS table.
	27