[Gd-chatter] r11213 - in trunk/documentation/gwydion/gdcore: project text
agent at gwydiondylan.org
agent at gwydiondylan.org
Sun Feb 25 08:01:34 CET 2007
Author: agent
Date: Sun Feb 25 08:01:14 2007
New Revision: 11213
Removed:
trunk/documentation/gwydion/gdcore/text/module.finalization.common-dylan.txt
Modified:
trunk/documentation/gwydion/gdcore/project/Menu.txt
trunk/documentation/gwydion/gdcore/project/Topics.txt
trunk/documentation/gwydion/gdcore/text/lang-notes.txt
trunk/documentation/gwydion/gdcore/text/library.common-dylan.txt
trunk/documentation/gwydion/gdcore/text/module.common-extensions.common-dylan.txt
trunk/documentation/gwydion/gdcore/text/module.functional-extensions.common-dylan.txt
trunk/documentation/gwydion/gdcore/text/module.simple-random.common-dylan.txt
trunk/documentation/gwydion/gdcore/text/name.Dmachine-word-size.txt
trunk/documentation/gwydion/gdcore/text/name.Dmaximum-signed-machine-word.txt
trunk/documentation/gwydion/gdcore/text/name.Dmaximum-unsigned-machine-word.txt
trunk/documentation/gwydion/gdcore/text/name.Dminimum-signed-machine-word.txt
trunk/documentation/gwydion/gdcore/text/name.Dminimum-unsigned-machine-word.txt
trunk/documentation/gwydion/gdcore/text/name.Dunfound.txt
trunk/documentation/gwydion/gdcore/text/name.Lexclusive-lockR.txt
trunk/documentation/gwydion/gdcore/text/name.LfloatR.txt
trunk/documentation/gwydion/gdcore/text/name.Lformat-string-conditionR.txt
trunk/documentation/gwydion/gdcore/text/name.LfunctionR.txt
trunk/documentation/gwydion/gdcore/text/name.LlockR.txt
trunk/documentation/gwydion/gdcore/text/name.Lmachine-wordR.txt
trunk/documentation/gwydion/gdcore/text/name.Lnot-owned-errorR.txt
trunk/documentation/gwydion/gdcore/text/name.LnotificationR.txt
trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt
trunk/documentation/gwydion/gdcore/text/name.Lread-write-lockR.txt
trunk/documentation/gwydion/gdcore/text/name.Lrecursive-lockR.txt
trunk/documentation/gwydion/gdcore/text/name.LsemaphoreR.txt
trunk/documentation/gwydion/gdcore/text/name.Lsimple-conditionR.txt
trunk/documentation/gwydion/gdcore/text/name.Lsimple-lockR.txt
trunk/documentation/gwydion/gdcore/text/name.Lstretchy-sequenceR.txt
trunk/documentation/gwydion/gdcore/text/name.LstringR.txt
trunk/documentation/gwydion/gdcore/text/name.LsynchronizationR.txt
trunk/documentation/gwydion/gdcore/text/name.LthreadR.txt
trunk/documentation/gwydion/gdcore/text/name.Ltimeout-exceededR.txt
trunk/documentation/gwydion/gdcore/text/name.associated-lock.txt
trunk/documentation/gwydion/gdcore/text/name.atomic-incrementX.txt
trunk/documentation/gwydion/gdcore/text/name.condition-to-string.txt
trunk/documentation/gwydion/gdcore/text/name.current-thread.txt
trunk/documentation/gwydion/gdcore/text/name.debug-assert.txt
trunk/documentation/gwydion/gdcore/text/name.debug-message.txt
trunk/documentation/gwydion/gdcore/text/name.difference.txt
trunk/documentation/gwydion/gdcore/text/name.dynamic-bind.txt
trunk/documentation/gwydion/gdcore/text/name.fill-tableX.txt
trunk/documentation/gwydion/gdcore/text/name.find-element.txt
trunk/documentation/gwydion/gdcore/text/name.find.txt
trunk/documentation/gwydion/gdcore/text/name.float-to-string.txt
trunk/documentation/gwydion/gdcore/text/name.foundQ.txt
trunk/documentation/gwydion/gdcore/text/name.function-definer.txt
trunk/documentation/gwydion/gdcore/text/name.ignorable.txt
trunk/documentation/gwydion/gdcore/text/name.ignore.txt
trunk/documentation/gwydion/gdcore/text/name.iterate.txt
trunk/documentation/gwydion/gdcore/text/name.join-thread.txt
trunk/documentation/gwydion/gdcore/text/name.merge-hash-ids.txt
trunk/documentation/gwydion/gdcore/text/name.ownedQ.txt
trunk/documentation/gwydion/gdcore/text/name.position.txt
trunk/documentation/gwydion/gdcore/text/name.release-all.txt
trunk/documentation/gwydion/gdcore/text/name.release.txt
trunk/documentation/gwydion/gdcore/text/name.remove-all-keysX.txt
trunk/documentation/gwydion/gdcore/text/name.subclass.txt
trunk/documentation/gwydion/gdcore/text/name.suppliedQ.txt
trunk/documentation/gwydion/gdcore/text/name.table-definer.txt
trunk/documentation/gwydion/gdcore/text/name.table-protocol.txt
trunk/documentation/gwydion/gdcore/text/name.thread-name.txt
trunk/documentation/gwydion/gdcore/text/name.thread-yield.txt
trunk/documentation/gwydion/gdcore/text/name.unfound.txt
trunk/documentation/gwydion/gdcore/text/name.unfoundQ.txt
trunk/documentation/gwydion/gdcore/text/name.unsupplied.txt
trunk/documentation/gwydion/gdcore/text/name.unsuppliedQ.txt
trunk/documentation/gwydion/gdcore/text/name.values-hash.txt
trunk/documentation/gwydion/gdcore/text/name.wait-for.txt
trunk/documentation/gwydion/gdcore/text/name.when.txt
trunk/documentation/gwydion/gdcore/text/name.with-lock.txt
Log:
Bug: 7344
Added docs from OD documentation.
Modified: trunk/documentation/gwydion/gdcore/project/Menu.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/project/Menu.txt (original)
+++ trunk/documentation/gwydion/gdcore/project/Menu.txt Sun Feb 25 08:01:14 2007
@@ -66,7 +66,6 @@
File: Dylan (no auto-title, module.dylan.dylan.txt)
File: Extensions (no auto-title, module.extensions.dylan.txt)
File: file-system (no auto-title, module.file-system.system.txt)
- File: finalization (no auto-title, module.finalization.common-dylan.txt)
File: format (no auto-title, module.format.io.txt)
File: format-out (no auto-title, module.format-out.io.txt)
File: functional-extensions (no auto-title, module.functional-extensions.common-dylan.txt)
Modified: trunk/documentation/gwydion/gdcore/project/Topics.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/project/Topics.txt (original)
+++ trunk/documentation/gwydion/gdcore/project/Topics.txt Sun Feb 25 08:01:14 2007
@@ -6,7 +6,7 @@
# instead.
-Ignore Keywords: key, note
+Ignore Keywords: key, note, object, target
#-------------------------------------------------------------------------------
Modified: trunk/documentation/gwydion/gdcore/text/lang-notes.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/lang-notes.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/lang-notes.txt Sun Feb 25 08:01:14 2007
@@ -32,6 +32,20 @@
+Topic: Table protocol and hashing
+=================================
+
+For efficiency, Common Dylan adopts a slightly different table protocol to
+that described by the DRM. Hashing functions take an additional _hash-state_
+argument and merge it into the _hash-state_ result. The function
+merge-hash-codes is replaced by #merge-hash-ids# because hash states are
+merged as part of the hashing process. The constant $permanent-hash-state is
+no longer required; the same effect can be achieved by returning the argument
+_hash-state_ unchanged as the result _hash-state_. Finally, #object-hash# has
+been altered to use the new protocol.
+
+
+
Topic: Define adjectives
========================
@@ -68,15 +82,17 @@
Call optimization:
-default-inline - The function is inlined normally.
+default-inline - Inline the function within a library, at the compiler's
+ discretion. Never inline a cross-library reference.
flushable - The function's value depends on global state, but it does not
change global state.
-inline - The function's body is duplicated at each call site.
-inline-only - ?
-may-inline - ?
+inline - Inline the function wherever the compiler can do so.
+inline-only - Forces every reference to the function to be inlined.
+may-inline - Inline the function within or between libraries, at the
+ compiler's discretion.
movable - The function's value does not depend on global state. The
value only depends on the function's arguments.
-not-inline - The function is never inlined.
+not-inline - Never inline the function.
sideways - ?
@@ -97,3 +113,140 @@
#<extended-integer>#s. #as# signals an error when converting an
#<extended-integer># to a #<integer>#, and the value does not fit in a
#<integer>#.
+
+
+
+Topic: Subclass relationships
+=============================
+
+In the language defined by the DRM, the only mechanism available for
+specializing such methods is to use singleton types. A singleton type
+specializer used in this way, by definition, gives a method applicable to
+exactly one type. In particular, such methods are not applicable to subtypes
+of the type in question. In order to define reusable methods on generic
+functions like this, we need a type which allows us to express applicability
+to a type and all its subtypes. This is provided by the #subclass# function.
+
+For an object O and class Y, the following #instance?# relationship
+applies:
+
+INSTANCE-1 - instance?(O, subclass(Y)) is true if and only if O is a class and
+O is a subclass of Y.
+
+For classes X and Y the following #subtype?# relationships hold (note that a
+rule applies only when no preceding rule matches):
+
+SUBTYPE-1 - subtype?(subclass(X), subclass(Y)) is true if and only if X is a
+subclass of Y.
+
+SUBTYPE-2 - subtype?(singleton(X), subclass(Y)) is true if and only if X is a
+class and X is a subclass of Y.
+
+SUBTYPE-3 - subtype?(subclass(X), singleton(Y)) is always false.
+
+SUBTYPE-4 - subtype?(subclass(X), Y) where Y is not a subclass type is true if
+Y is #<class># or any proper superclass of #<class># (including #<object>#,
+any implementation-defined supertypes, and unions involving any of these).
+There may be other implementation-defined combinations of types X and Y for
+which this is also true.
+
+SUBTYPE-5 - subtype?(X, subclass(Y)) where X is not a subclass type is true if
+Y is #<object># or any proper supertype of #<object># and X is a subclass of
+#<class>#.
+
+Note that by subclass relationships SUBTYPE-4 and SUBTYPE-5, we get this
+correspondence: <class> and subclass(<object>) are type equivalent.
+
+Where the #subtype?# test has not been sufficient to determine an ordering for
+a method's argument position, the following further method-ordering rules
+apply to cases involving subclass types (note that a rule applies only when no
+preceding rule matches):
+
+SPECIFICITY+1 - subclass(X) precedes subclass(Y) when the argument is a class
+C and X precedes Y in the class precedence list of C.
+
+SPECIFICITY+2 - subclass(X) always precedes Y, Y not a subclass type. That
+is, applicable subclass types precede any other applicable class-describing
+specializer.
+
+The constraints implied by sealing come by direct application of sealing rules
+1-3 (see page 136 of the DRM) and the following disjointness criteria for
+subclass types (note that a rule applies only when no preceding rule matches):
+
+DISJOINTNESS+1 - A subclass type subclass(X) and a type Y are disjoint if Y is
+disjoint from #<class>#, or if Y is a subclass of #<class># without instance
+classes that are also subclasses of X.
+
+DISJOINTNESS+2 - Two subclass types subclass(X) and subclass(Y) are disjoint
+if the classes X and Y are disjoint.
+
+DISJOINTNESS+3 - A subclass type subclass(X) and a singleton type singleton(O)
+are disjoint unless O is a class and O is a subclass of X.
+
+The guiding principle behind the semantics is that, as far as possible,
+methods on classes called with an instance should behave isomorphically to
+corresponding methods on corresponding subclass types called with the class of
+that instance. So, for example, given the heterarchy
+
+(diagram)
+ <object>
+ |
+ <A>
+ / \
+ <B> <C>
+ \ /
+ <D>
+(end)
+
+and methods
+
+: method foo (<A>)
+: method foo (<B>)
+: method foo (<C>)
+: method foo (<D>)
+: method foo-using-type (subclass(<A>))
+: method foo-using-type (subclass(<B>))
+: method foo-using-type (subclass(<C>))
+: method foo-using-type (subclass(<D>))
+
+that for a direct instance D1 of <D>
+
+: foo-using-type(<D>)
+
+should behave analogously to
+
+: foo(D1)
+
+with respect to method selection.
+
+
+Example:
+
+(example)
+define class <A> (<object>) end;
+define class <B> (<A>) end;
+define class <C> (<A>) end;
+define class <D> (<B>, <C>) end;
+define method make (class :: subclass(<A>), #key)
+ print("Making an <A>");
+ next-method();
+end method;
+define method make (class :: subclass(<B>), #key)
+ print("Making a <B>");
+ next-method();
+end method;
+define method make (class :: subclass(<C>), #key)
+ print("Making a <C>");
+ next-method();
+end method;
+define method make (class :: subclass(<D>), #key)
+ print("Making a <D>");
+ next-method();
+end method;
+? make(<D>);
+Making a <D>
+Making a <B>
+Making a <C>
+Making an <A>
+{instance of <D>}
+(end)
Modified: trunk/documentation/gwydion/gdcore/text/library.common-dylan.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/library.common-dylan.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/library.common-dylan.txt Sun Feb 25 08:01:14 2007
@@ -10,7 +10,6 @@
- #Module common-dylan#
- #Module common-extensions#
- #Module Dylan#
-- #Module finalization#
- #Module functional-extensions#
- #Module functional-objects-extras#
- #Module gwydion-extensions#
Modified: trunk/documentation/gwydion/gdcore/text/module.common-extensions.common-dylan.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/module.common-extensions.common-dylan.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/module.common-extensions.common-dylan.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Module: Module common-extensions
==============================
-The common-extensions module.
+Miscellaneous extensions to the Dylan language.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/module.functional-extensions.common-dylan.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/module.functional-extensions.common-dylan.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/module.functional-extensions.common-dylan.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Module: Module functional-extensions
==============================
-The functional-extensions module.
+Provided for backward compatibility.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/module.simple-random.common-dylan.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/module.simple-random.common-dylan.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/module.simple-random.common-dylan.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Module: Module simple-random
==============================
-The simple-random module.
+A simple facility for generating pseudo-random integers.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Dmachine-word-size.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Dmachine-word-size.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Dmachine-word-size.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Constant: $machine-word-size
==============================
-A constant.
+The number of bits in the representation of a #<machine-word>#.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Dmaximum-signed-machine-word.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Dmaximum-signed-machine-word.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Dmaximum-signed-machine-word.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Constant: $maximum-signed-machine-word
==============================
-A constant.
+The largest machine word, when interpreted as a signed integer value.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Dmaximum-unsigned-machine-word.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Dmaximum-unsigned-machine-word.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Dmaximum-unsigned-machine-word.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Constant: $maximum-unsigned-machine-word
==============================
-A constant.
+The largest machine word, when interpreted as an unsigned integer value.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Dminimum-signed-machine-word.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Dminimum-signed-machine-word.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Dminimum-signed-machine-word.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Constant: $minimum-signed-machine-word
==============================
-A constant.
+The smallest machine word, when interpreted as a signed integer value.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Dminimum-unsigned-machine-word.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Dminimum-unsigned-machine-word.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Dminimum-unsigned-machine-word.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Constant: $minimum-unsigned-machine-word
==============================
-A constant.
+The smallest machine word, when interpreted as an unsigned integer value.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Dunfound.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Dunfound.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Dunfound.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Constant: $unfound
==============================
-A constant.
+A unique value that can be used to indicate that a search operation failed.
Exported from:
@@ -19,3 +19,9 @@
------------------------------
unknown
+
+See also:
+------------------------------
+- #found?#
+- #unfound?#
+- #unfound#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lexclusive-lockR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lexclusive-lockR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lexclusive-lockR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,20 @@
Class: <exclusive-lock>
==============================
-A class.
+The class of locks which prohibit unlocking by threads that do not own the
+lock.
+
+The notion of ownership is directly supported by the class, and a thread can
+test whether an #<exclusive-lock># is currently owned. An instance of
+#<exclusive-lock># can only be owned by one thread at a time, by calling
+#wait-for# on the lock.
+
+Once owned, any attempt by any other thread to wait for the lock will cause
+that thread to block. It is an error for a thread to release an
+#<exclusive-lock># if another thread owns it.
+
+#<exclusive-lock># has no direct instances; calling #make# on
+#<exclusive-lock># returns an instance of #<simple-lock>#.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.LfloatR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LfloatR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LfloatR.txt Sun Feb 25 08:01:14 2007
@@ -33,6 +33,7 @@
- #float-digits#
- #float-precision#
- #float-radix#
+- #float-to-string#
- #integer-decode-float#
- #scale-float#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lformat-string-conditionR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lformat-string-conditionR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lformat-string-conditionR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Class: <format-string-condition>
==============================
-A class.
+The class of conditions that take a format string.
Exported from:
@@ -29,4 +29,6 @@
- #<xml-error>#
-
+See also:
+------------------------------
+#Module format#
Modified: trunk/documentation/gwydion/gdcore/text/name.LfunctionR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LfunctionR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LfunctionR.txt Sun Feb 25 08:01:14 2007
@@ -45,6 +45,7 @@
- #concatenate-map#
- #conjoin#
- #curry#
+- #difference#
- #disjoin#
- #do#
- #do-directory#
Modified: trunk/documentation/gwydion/gdcore/text/name.LlockR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LlockR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LlockR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,20 @@
Class: <lock>
==============================
-A class.
+The class of locks. Locks are synchronization objects which change state when
+they are _claimed_ (using #wait-for#), and revert state when _released_ (using
+#release#).
+
+It is normally necessary for programs to ensure that locks are released,
+otherwise there is the possibility of deadlock. Locks may be used to restrict
+the access of other threads to shared resources between the synchronization
+and the release. It is common for a protected operation to be performed by a
+body of code which is evaluated in a single thread between synchronization and
+release. A macro #with-lock# is provided for this purpose. When a thread uses
+a lock for mutual exclusion in this way, the thread is said to _own the lock_.
+
+#<lock># has no direct instances; calling #make# on #<lock># returns an
+instance of #<simple-lock>#.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Lmachine-wordR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lmachine-wordR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lmachine-wordR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,11 @@
Class: <machine-word>
==============================
-A class.
+The class #<machine-word># represents a limited range of integral values. The
+representation used has the natural size suggested by the implementation
+architecture. On the PC, a #<machine-word># is 32 bits wide. The class
+#<machine-word># is disjoint from all other classes specified by the Dylan
+language.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Lnot-owned-errorR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lnot-owned-errorR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lnot-owned-errorR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Class: <not-owned-error>
==============================
-A class.
+This may be signaled when an attempt is made to release a notification when
+the associated lock is not owned by the current thread.
Exported from:
@@ -17,8 +18,7 @@
Superclasses:
------------------------------
-- <synchronization-condition>
- - #<error>#
+- #<error>#
Modified: trunk/documentation/gwydion/gdcore/text/name.LnotificationR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LnotificationR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LnotificationR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,66 @@
Class: <notification>
==============================
-A class.
+The class of objects that can be used to notify threads of a change of state
+elsewhere in the program. Notifications are used in association with locks,
+and are sometimes called condition variables. They may be used to support the
+sharing of data between threads using monitors. Each #<notification># is
+permanently associated with a #<simple-lock>#, although the same lock may be
+associated with many notifications.
+
+The required lock is associated with the notification, and it is only possible
+to wait for, or release, the notification if the lock is owned.
+
+Threads wait for the change of state to be notified by calling #wait-for#.
+Threads notify other threads of the change of state by calling #release#.
+
+
+Example:
+------------------------------
+This example shows how to use a notification and an associated lock to
+implement a queue. The variable _*queue*_ is the actual queue object (a
+#<deque>#). Queue access is performed by interlocking pushes and pops on the
+#<deque>#. The _*queue*_ variable can be a constant, since it is the #<deque>#
+which is mutated and not the value of _*queue*_.
+
+: define constant *queue* = make(<deque>);
+
+The variable _*lock*_ is used to isolate access to the queue
+
+: define constant *lock* = make(<lock>);
+
+The variable _*something-queued*_ is a notification which is used to notify
+other threads that an object is being put onto an empty queue.
+
+: define constant *something-queued* =
+: make(<notification>, lock: *lock*);
+
+The function _put-on-queue_ pushes an object onto the queue. If the queue was
+initially empty, then all threads which are waiting for the queue to fill are
+notified that there is a new entry.
+
+: define method put-on-queue (object) => ()
+: with-lock (*lock*)
+: if (*queue*.empty?)
+: release-all(*something-queued*)
+: end;
+: push(*queue*, object)
+: end with-lock
+: end method;
+
+The _get-from-queue_ function returns an object from the queue. If no object
+is immediately available, then it blocks until it receives a notification that
+the queue is no longer empty. After receiving the notification it tests again
+to see if an object is present, in case it was popped by another thread.
+
+: define method get-from-queue () => (object)
+: with-lock (*lock*)
+: while (*queue*.empty?)
+: wait-for(*something-queued*)
+: end;
+: pop(*queue*)
+: end with-lock
+: end method;
Exported from:
@@ -15,6 +74,11 @@
concrete free sealed
+Make keyword:
+------------------------------
+lock: - An instance of #<simple-lock>#. Required.
+
+
Superclasses:
------------------------------
- #<synchronization>#
@@ -22,6 +86,7 @@
Functions on <notification>:
------------------------------
+- #associated-lock#
- #release-all#
Modified: trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt Sun Feb 25 08:01:14 2007
@@ -80,7 +80,6 @@
- #as-lowercase#
- #as-lowercase!#
- #assoc#
-- #associated-lock#
- #as-uppercase#
- #as-uppercase!#
- #break#
@@ -127,7 +126,6 @@
- #debugger-message#
- #debug-message#
- #dest-index#
-- #difference#
- #direct-instance-of#
- #disjoin#
- #do#
@@ -164,7 +162,6 @@
- #first#
- #first-setter#
- #float-decimal-digits#
-- #float-to-string#
- #foldl#
- #foldr#
- #format#
@@ -192,7 +189,6 @@
- #instance?#
- #integral?#
- #intersection#
-- #join-thread#
- #key-exists?#
- #last#
- #last-setter#
@@ -368,7 +364,6 @@
- #tail-setter#
- #third#
- #third-setter#
-- #thread-name#
- #tightly-bound-to-next-token?#
- #token-value#
- #translate#
@@ -421,7 +416,6 @@
- #as-lowercase#
- #as-lowercase!#
- #assoc#
-- #associated-lock#
- #as-uppercase#
- #as-uppercase!#
- #backward-iteration-protocol#
@@ -477,7 +471,6 @@
- #first#
- #first-setter#
- #float-decimal-digits#
-- #float-to-string#
- #format-out#
- #forward-iteration-protocol#
- #ftp-parser#
@@ -623,7 +616,6 @@
- #tail-setter#
- #third#
- #third-setter#
-- #thread-name#
- #tightly-bound-to-next-token?#
- #token-value#
- #type-error-location#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lread-write-lockR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lread-write-lockR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lread-write-lockR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,28 @@
Class: <read-write-lock>
==============================
-A class.
+The class of locks that can have multiple readers but only one writer.
+
+The #<read-write-lock># class can be locked in either of two modes, _read_ and
+_write_. A _write_ lock is exclusive, and implies ownership of the lock.
+However, a _read_ lock is non-exclusive, and an instance can be locked
+multiple times in read mode, whether by multiple threads, recursively by a
+single thread, or a combination of both.
+
+A #<read-write-lock># can only be locked in _write_ mode if the lock is free,
+and the operation will block if necessary. It can only be freed by the thread
+that owns it.
+
+A #<read-write-lock># can be locked in _read_ mode provided that it is not
+owned with a _write_ lock. The operation will block while the lock is owned.
+Each time it is locked in _read_ mode, an internal counter is incremented.
+This counter is decremented each time a read-mode lock is released. The lock
+is freed when the counter becomes zero.
+
+The #<read-write-lock># class is less efficient than the other lock classes
+defined in the Threads library. However, it provides an efficient and
+convenient means to protect data that is frequently read and may occasionally
+be written by multiple concurrent threads.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Lrecursive-lockR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lrecursive-lockR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lrecursive-lockR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,10 @@
Class: <recursive-lock>
==============================
-A class.
+The class of locks that can be locked recursively. A thread can lock a
+#<recursive-lock># multiple times, recursively, but the lock must later be
+released the same number of times. The lock will be freed on the last of these
+releases.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.LsemaphoreR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LsemaphoreR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LsemaphoreR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,18 @@
Class: <semaphore>
==============================
-A class.
+The class of traditional counting semaphores. An instance of #<semaphore>#
+contains a counter in its internal state. Calling #release# on a semaphore
+increments the internal count. Calling #wait-for# on a semaphore decrements
+the internal count, unless it is zero, in which case the thread blocks until
+another thread releases the semaphore.
+
+Semaphores are less efficient than exclusive locks, but they have asynchronous
+properties which may be useful (for example for managing queues or pools of
+shared resources). Semaphores may be released by any thread, so there is no
+built-in concept of a thread owning a semaphore. It is not necessary for a
+thread to release a semaphore after waiting for it -- although semaphores may
+be used as locks if they do.
Exported from:
@@ -15,6 +26,18 @@
concrete primary open
+Make keywords:
+------------------------------
+initial-count - An instance of #<integer>#. This is a non-negative value
+ corresponding to the initial state of the internal counter.
+ The default value is 0.
+
+maximum-count - An instance of #<integer>#. This is a non-negative value
+ corresponding to the maximum permitted value of the internal
+ counter. The default value is the largest value supported by
+ the implementation, not be smaller than 10000.
+
+
Superclasses:
------------------------------
- #<lock>#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lsimple-conditionR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lsimple-conditionR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lsimple-conditionR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Class: <simple-condition>
==============================
-A class.
+The class of simple conditions.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Lsimple-lockR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lsimple-lockR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lsimple-lockR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,10 @@
Class: <simple-lock>
==============================
-A class.
+A simple and efficient lock. The #<simple-lock># class represents the most
+simple and efficient mutual exclusion synchronization primitive. It is an
+error to lock a #<simple-lock># recursively. An attempt to do so might result
+in an error being signaled, or deadlock occurring.
Exported from:
@@ -20,4 +23,6 @@
- #<exclusive-lock>#
-
+Functions returning <simple-lock>:
+------------------------------
+- #associated-lock#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lstretchy-sequenceR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lstretchy-sequenceR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lstretchy-sequenceR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Class: <stretchy-sequence>
==============================
-A class.
+The class of stretchy sequences.
Exported from:
@@ -19,7 +19,7 @@
Superclasses:
------------------------------
- #<stretchy-collection>#
- - #<sequence>#
+- #<sequence>#
Subclasses:
Modified: trunk/documentation/gwydion/gdcore/text/name.LstringR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LstringR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LstringR.txt Sun Feb 25 08:01:14 2007
@@ -82,6 +82,7 @@
------------------------------
- #as-iso8601-string#
- #condition-format-string#
+- #float-to-string#
- #format-to-string#
- #integer-to-string#
- #local-time-zone-name#
@@ -94,6 +95,7 @@
- #print-to-string#
- #regexp-replace#
- #split#
+- #thread-name#
- #translate#
Modified: trunk/documentation/gwydion/gdcore/text/name.LsynchronizationR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LsynchronizationR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LsynchronizationR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,16 @@
Class: <synchronization>
==============================
-A class.
+The class of objects that are used for inter-thread synchronization.
+
+There is no explicit mechanism in the library to block on a number of
+synchronization objects simultaneously, until synchronization can be achieved
+with one of them. This mechanism can be implemented by creating a new thread
+to wait for each synchronization object, and arranging for each thread to
+release a notification once synchronization has been achieved.
+
+The _name_ keyword is a string that is used as the synchronization object's
+name for convenience purposes, such as debugging.
Exported from:
@@ -15,6 +24,11 @@
abstract free open
+Make keywords:
+------------------------------
+name: - An instance of #<string>#. Optional.
+
+
Superclasses:
------------------------------
- #<object>#
Modified: trunk/documentation/gwydion/gdcore/text/name.LthreadR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LthreadR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LthreadR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,32 @@
Class: <thread>
==============================
-A class.
+The class representing a thread of control executing a function.
+
+The function is called with no arguments in the empty dynamic environment of
+the new thread. The thread terminates when the function returns.
+
+The function is executable immediately. You can suspend a new thread (almost)
+immediately on creation by arranging for it to synchronize on an unavailable
+resource upon entry to the function.
+
+The optional _priority_ keyword provides a scheduling priority for the thread.
+The higher the value, the greater the priority. The default value is zero,
+which is also the value of the constant #$normal-priority#, one of several
+constants that correspond to useful priority levels. The library offers no way
+to change the priority of a thread dynamically.
+
+The following constants, listed in order of increasing value, may be useful as
+values for the optional priority keyword.
+
+- #$low-priority#
+- #$background-priority#
+- #$normal-priority#
+- #$interactive-priority#
+- #$high-priority#
+
+The _name_ keyword is a string that is used as the function's name for
+convenience purposes, such as debugging.
Exported from:
@@ -15,6 +40,14 @@
concrete free sealed
+Make keywords:
+------------------------------
+function - An instance of #<function>#. Required. The function must not have
+ any required arguments.
+name - An instance of #<string># or #f. The default is #f.
+priority - An instance of #<integer>#. The default is #$normal-priority#.
+
+
Superclasses:
------------------------------
- #<object>#
@@ -23,6 +56,7 @@
Functions on <thread>:
------------------------------
- #join-thread#
+- #thread-name#
Functions returning <thread>:
Modified: trunk/documentation/gwydion/gdcore/text/name.Ltimeout-exceededR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Ltimeout-exceededR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Ltimeout-exceededR.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Class: <timeout-exceeded>
==============================
-A class.
+This is signaled when #with-lock# did not succeed in claiming a lock within
+the timeout period.
Exported from:
@@ -17,8 +18,7 @@
Superclasses:
------------------------------
-- <synchronization-condition>
- - #<serious-condition>#
+- #<serious-condition>#
Modified: trunk/documentation/gwydion/gdcore/text/name.associated-lock.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.associated-lock.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.associated-lock.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Generic: associated-lock
==============================
-A generic function.
+Returns the lock associated with a notification object.
Exported from:
@@ -17,12 +17,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+notification - An instance of #<notification>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+lock - An instance of #<simple-lock>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.atomic-incrementX.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.atomic-incrementX.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.atomic-incrementX.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,15 @@
Macro: atomic-increment!
==============================
-A macro.
+Atomically increments a variable containing a numeric value. The value of the
+variable is evaluated one or more times to determine the initial value. A new
+value is computed from this value by adding 1 using #+#. The new value is
+atomically stored back into _var_. The macro returns the new value of _var_.
+
+The following example atomically increments _*number-detected*_ by 1, and
+returns the incremented value.
+
+: atomic-increment!(*number-detected*);
Exported from:
@@ -9,10 +17,13 @@
- #Module threads#
-Definition:
+Macro call:
+------------------------------
+: atomic-increment!( (var) )
+
+
+Arguments:
------------------------------
-:
- function macro
-
+var - A variable name.
Modified: trunk/documentation/gwydion/gdcore/text/name.condition-to-string.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.condition-to-string.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.condition-to-string.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Generic: condition-to-string
==============================
-A generic function.
+Returns a string representation of a condition object.
Exported from:
@@ -17,12 +17,12 @@
Arguments:
------------------------------
-arg - An instance of #<condition>#.
+condition - An instance of #<condition>#.
Values:
------------------------------
-val - An instance of type-union(<false>, <string>).
+string - An instance of type-union(<false>, <string>).
Modified: trunk/documentation/gwydion/gdcore/text/name.current-thread.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.current-thread.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.current-thread.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Function: current-thread
==============================
-A function.
+Returns the current thread.
Exported from:
@@ -12,7 +12,7 @@
Values:
------------------------------
-val - An instance of #<thread>#.
+thread - An instance of #<thread>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.debug-assert.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.debug-assert.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.debug-assert.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Macro: debug-assert
==============================
-A macro.
+Identical to #assert#.
Exported from:
@@ -11,10 +11,6 @@
- #Module common-extensions#
-Definition:
+See:
------------------------------
-:
- function macro
-
-
-
+#assert#
\ No newline at end of file
Modified: trunk/documentation/gwydion/gdcore/text/name.debug-message.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.debug-message.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.debug-message.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Function: debug-message
==============================
-A function.
+Formats a string and outputs it to the debugger. Calls #debugger-message#.
Exported from:
@@ -13,8 +13,9 @@
Arguments:
------------------------------
-arg - An instance of #<byte-string>#.
-#rest more - Instances of #<object>#.
+format-string - An instance of #<byte-string>#.
+#rest format-args - Instances of #<object>#. Parameters to substitute for
+ format directives in _format-string_.
Modified: trunk/documentation/gwydion/gdcore/text/name.difference.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.difference.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.difference.txt Sun Feb 25 08:01:14 2007
@@ -1,8 +1,11 @@
Generic: difference
==============================
-A generic function.
+Returns a sequence containing the elements of one sequence that are not
+members of a second. You can supply a membership test function as _test_.
+> difference(#(1,2,3), #(2,3,4));
+> ⇒ #(1)
Exported from:
------------------------------
@@ -18,14 +21,14 @@
Arguments:
------------------------------
-arg - An instance of #<sequence>#.
-arg - An instance of #<sequence>#.
-test: - An instance of #<object>#. The default is #f.
+sequence-1 - An instance of #<sequence>#.
+sequence-2 - An instance of #<sequence>#.
+test: - An instance of #<function>#. The default is #==#.
Values:
------------------------------
-val - An instance of #<sequence>#.
+result-sequence - An instance of #<sequence>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.dynamic-bind.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.dynamic-bind.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.dynamic-bind.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,35 @@
Macro: dynamic-bind
==============================
-A macro.
+Executes a body of code in a context in which variables are dynamically
+rebound.
+
+This macro executes _body_ with the specified _variables_ rebound in the
+dynamic environment, each variable being initialized to the results of
+evaluating the _initialization_ expressions. In other words, the variables are
+initialized to new values on entry to the body but restored to their old
+values once the body has finished executing, whether because it finishes
+normally, or because of a non-local transfer of control. The _variables_ must
+be the name of a thread variable in the module scope.
+
+An alternative form calls a function to perform the actual re-binding. This
+function is named x-dynamic-binder, where _x_ is _binder-name_. This function
+is analogous to the x-setter functions used in expressions like x := 3. The
+function takes the _initialization_ value, the _body_, and optional additional
+arguments.
+
+The alternative form will work with the "." and "[]" syntaxes for function
+calls. For example,
+
+: dynamic-bind (object.a-slot = new-slot-val())
+: inner-body(object)
+: end;
+
+expands into code equivalent to
+
+: a-slot-dynamic-binder(new-slot-val(),
+: method () inner-body(object) end,
+: object)
Exported from:
@@ -9,10 +37,27 @@
- #Module threads#
-Definition:
+Macro call:
------------------------------
-:
- statement macro
-
+: dynamic-bind ( (variable) = (initialization), ... )
+: (body)
+: end
+
+: dynamic-bind ( (binder-name) ( (args) ) = (initialization), ... )
+: (body)
+: end
+
+
+Arguments:
+------------------------------
+variable - A thread variable name.
+
+binder-name - Part of a function name. The full function name is
+ (binder-name)-dynamic-binder. The function's signature is
+ ( _initialization_, _body_, _args_ ) => ().
+
+initialization - An expression, whose value is assigned to _variable_ in
+ _body_ or passed to the _binder-name_ function.
+body - A series of semicolon-separated expressions.
Modified: trunk/documentation/gwydion/gdcore/text/name.fill-tableX.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.fill-tableX.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.fill-tableX.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,17 @@
Function: fill-table!
==============================
-A function.
+Fills a table with the keys and elements supplied.
+
+This function interprets _keys-and-elements_ as key-element pairs, that is, it
+treats the first element as a table key, the second as the table element
+corresponding to that key, and so on. The keys and elements should be suitable
+for table.
+
+Because _keys-and-elements_ is treated as a sequence of paired key-element
+values, it should contain an even number of elements; if it contains an odd
+number of elements, #fill-table!# ignores the last element (which would have
+been treated as a key).
Exported from:
@@ -12,13 +22,14 @@
Arguments:
------------------------------
-arg - An instance of #<table>#.
-arg - An instance of #<sequence>#.
+table - An instance of #<table>#.
+keys-and-elements - An instance of #<sequence>#, containing alternate keys and
+ elements.
Values:
------------------------------
-val - An instance of #<table>#.
+table - An instance of #<table>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.find-element.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.find-element.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.find-element.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,10 @@
Generic: find-element
==============================
-A generic function.
+Returns an element from a collection such that the element satisfies a
+predicate. This function is identical to #find-key#, but it returns the
+element that satisfies _predicate_ rather than the key that corresponds to the
+element.
Exported from:
@@ -17,10 +20,10 @@
Arguments:
------------------------------
-arg - An instance of #<collection>#.
-arg - An instance of #<function>#.
-skip: - An instance of #<integer>#. Required.
-failure: - An instance of #<object>#. The default is #f.
+collection - An instance of #<collection>#.
+predicate - An instance of #<function>#.
+skip: - An instance of #<integer>#. The default is 0.
+failure: - An instance of #<object>#. The default is #f.
Values:
Modified: trunk/documentation/gwydion/gdcore/text/name.find.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.find.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.find.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Generic: find
==============================
-Find an element satisfying a predicate.
+Find an element satisfying a predicate. Similar to #find-element#.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.float-to-string.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.float-to-string.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.float-to-string.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Generic: float-to-string
==============================
-A generic function.
+Formats a floating-point number to a string. It uses scientific notation where
+necessary.
Exported from:
@@ -17,12 +18,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+float - An instance of #<float>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+string - An instance of #<string>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.foundQ.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.foundQ.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.foundQ.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Function: found?
==============================
-A function.
+Returns true if an object is not equal to #$unfound#, and false otherwise.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.function-definer.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.function-definer.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.function-definer.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,26 @@
Macro: function-definer
==============================
-A macro.
+Defines a constant binding in the current module and initializes it to a new
+function.
+
+The following functions return the same values as they would if the function
+had been defined as a bare method with the same signature:
+
+- #function-specializers#
+- #function-arguments#
+- #function-return-values#
+
+Calling some of the following reflective operations on a function defined with
+_define function_ may be an error:
+
+- #generic-function-methods#
+- #add-method#
+- #generic-function-mandatory-keywords#
+- #sorted-applicable-methods#
+- #find-method#
+- #remove-method#
+- #applicable-method?#
Exported from:
@@ -10,10 +29,23 @@
- #Module Dylan#
-Definition:
+Macro Call:
+------------------------------
+: define (adjectives) function (name) (parameters) => (values) (options)
+: (body)
+: end function (name)
+
+
+Arguments:
------------------------------
-:
- body-style define macro
+adjectives - Gwydion Dylan allows the following adjectives: not-inline,
+ default-inline, may-inline, inline, inline-only, movable,
+ flushable. The default is sealed. See #Define adjectives#.
+name - A binding name.
+parameters - A parameter list. May be empty.
+values - A value list. May be omitted.
+body - A method body; a series of semicolon-separated expressions.
+
Modified: trunk/documentation/gwydion/gdcore/text/name.ignorable.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.ignorable.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.ignorable.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Function: ignorable
==============================
-A function.
+A compiler directive that tells the compiler it need not issue a warning if its argument is bound but not referenced.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.ignore.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.ignore.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.ignore.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Function: ignore
==============================
-A function.
+A compiler directive that tells the compiler it must not issue a warning if
+its argument is bound but not referenced.
Exported from:
@@ -16,4 +17,6 @@
#rest more - Instances of #<object>#.
-
+See also:
+------------------------------
+#ignorable#
Modified: trunk/documentation/gwydion/gdcore/text/name.iterate.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.iterate.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.iterate.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,13 @@
Macro: iterate
==============================
-A macro.
+Defines a function that can be used to iterate over a body. It is similar to
+#for#, but allows you to control when iteration will occur.
+
+It creates a function called _name_ which will perform a single step of the
+iteration at a time; _body_ can call _name_ whenever it wants to iterate
+another step. The form evaluates by calling the new function with the initial
+values specified.
Exported from:
@@ -10,10 +16,18 @@
- #Module common-extensions#
-Definition:
+Macro call:
------------------------------
-:
- statement macro
+: iterate (name) ( (argument) = (init-value), ... )
+: (body)
+: end iterate
+Arguments:
+------------------------------
+name - Name of a function to be defined.
+argument - An argument for _name_. Optional.
+init-value - Optional initial value for _argument_.
+body - Iteration body. May call the _name_ function with _arguments_ to
+ repeat.
Modified: trunk/documentation/gwydion/gdcore/text/name.join-thread.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.join-thread.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.join-thread.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,23 @@
Function: join-thread
==============================
-A function.
+Waits for another, existing, thread to terminate, by blocking if necessary,
+and then returns the values of its function. The function returns the thread
+object that was joined, along with any values its function returns.
+
+If more than one thread is passed to #join-thread#, the current thread blocks
+until the first of those threads terminates. The values returned are those of
+the first thread to terminate.
+
+If one or more of the multiple threads has already terminated at the time of
+the call, then one of those terminated threads is joined. When more than one
+thread has already terminated, it is undefined which of those threads the
+implementation will join.
+
+It is an error to pass a thread to #join-thread# if it has already been joined
+in a previous call to #join-thread#. It is an error to pass a thread to
+#join-thread# if that thread is also being processed by another simultaneous
+call to #join-thread# from another thread.
Exported from:
@@ -12,14 +28,15 @@
Arguments:
------------------------------
-arg - An instance of #<thread>#.
-#rest more - Instances of #<object>#.
+thread - An instance of #<thread>#. A thread to join.
+#rest threads - Instances of #<thread>#. More threads to join.
Values:
------------------------------
-val - An instance of #<thread>#.
-#rest more - Instances of #<object>#.
+thread-joined - An instance of #<thread>#. The thread that was joined.
+#rest more - Zero or more instances of #<object>#. The values returned from
+ the thread that was joined.
Modified: trunk/documentation/gwydion/gdcore/text/name.merge-hash-ids.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.merge-hash-ids.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.merge-hash-ids.txt Sun Feb 25 08:01:14 2007
@@ -12,7 +12,7 @@
then the order of the argument pairs matters because the algorithm used need
not be either commutative or associative. It is best to provide a true value
for ordered when possible, as this may result in a better distribution of hash
-ids. However, ordered must only be true if this will not cause the hash
+ids. However, _ordered_ must only be true if this will not cause the hash
function to violate the second constraint on hash functions, described on page
123 of the _Dylan Reference Manual_.
Modified: trunk/documentation/gwydion/gdcore/text/name.ownedQ.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.ownedQ.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.ownedQ.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Generic: owned?
==============================
-A generic function.
+Tests whether an exclusive lock has been claimed by the current thread.
Exported from:
@@ -17,12 +17,16 @@
Arguments:
------------------------------
-arg - An instance of #<exclusive-lock>#.
+object - An instance of #<exclusive-lock>#.
Values:
------------------------------
-val - An instance of #<boolean>#.
+owned? - An instance of #<boolean>#.
+Methods: owned?
+==============================
+owned? - The method on #<read-write-lock># returns true if the current thread
+ owns the lock in write mode.
Modified: trunk/documentation/gwydion/gdcore/text/name.position.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.position.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.position.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,15 @@
Generic: position
==============================
-A generic function.
+Returns the key at which a particular value occurs in a sequence.
+
+If _predicate_ is supplied, #position# uses it as an equivalence predicate for
+comparing _sequence_'s elements to _value_. It should take two objects and
+return a boolean. The default predicate used is #==#.
+
+The _skip_ argument is interpreted as it is by Dylan's #find-key# function.
+#position# ignores the first _skip_ elements that match _value_, and if _skip_
+or fewer elements satisfy _predicate_, it returns #f.
Exported from:
@@ -17,16 +25,15 @@
Arguments:
------------------------------
-arg - An instance of #<sequence>#.
-arg - An instance of #<object>#.
-predicate: - An instance of #<function>#. Required.
-skip: - An instance of #<integer>#. Required.
-count: - An instance of #<object>#. The default is #f.
+sequence - An instance of #<sequence>#.
+value - An instance of #<object>#.
+predicate: - An instance of #<function>#. Defaults to #==#.
+skip: - An instance of #<integer>#. Defaults to 0.
Values:
------------------------------
-val - An instance of type-union(<integer>, <false>).
+key - An instance of type-union(<integer>, <false>).
Modified: trunk/documentation/gwydion/gdcore/text/name.release-all.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.release-all.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.release-all.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,9 @@
Function: release-all
==============================
-A function.
+Release a notification to all the threads that are blocked and waiting for it.
+Those threads will then necessarily have to compete for the lock associated
+with the notification.
Exported from:
@@ -12,7 +14,7 @@
Arguments:
------------------------------
-arg - An instance of #<notification>#.
+notification - An instance of #<notification>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.release.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.release.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.release.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,10 @@
Generic: release
==============================
-A generic function.
+Releases a synchronization object, potentially making it available to other
+threads. Individual methods describe what this means for each class of
+synchronization. This function does not block for any of the subclasses of
+#<synchronization># provided by the library.
Exported from:
@@ -17,7 +20,7 @@
Arguments:
------------------------------
-arg - An instance of #<synchronization>#.
+object - An instance of #<synchronization>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.remove-all-keysX.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.remove-all-keysX.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.remove-all-keysX.txt Sun Feb 25 08:01:14 2007
@@ -4,6 +4,9 @@
Remove all keys from a table. This function iterates through all the keys and
calls #remove-key!# on each one.
+_Note_: To empty collections that are not instances of
+#<mutable-explicit-key-collection>#, use #size-setter#.
+
Exported from:
------------------------------
Modified: trunk/documentation/gwydion/gdcore/text/name.subclass.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.subclass.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.subclass.txt Sun Feb 25 08:01:14 2007
@@ -1,8 +1,9 @@
Function: subclass
==============================
-A function.
-
+Returns a type representing a class and its subclasses. Without #subclass#,
+methods on generic functions (such as #make# and #as#) that take types as
+arguments are impossible to reuse without resorting to ad hoc techniques.
Exported from:
------------------------------
@@ -13,12 +14,14 @@
Arguments:
------------------------------
-arg - An instance of #<class>#.
+class - An instance of #<class>#.
Values:
------------------------------
-val - An instance of #<subclass>#.
-
+subclass-type - An instance of #<subclass>#.
+See also:
+------------------------------
+#Subclass relationships#
Modified: trunk/documentation/gwydion/gdcore/text/name.suppliedQ.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.suppliedQ.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.suppliedQ.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Function: supplied?
==============================
-A function.
+Returns true if its argument, the keyword argument of a function, is not the unique "unsupplied" value, and false if it is.
Exported from:
@@ -12,12 +12,15 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+object - An instance of #<object>#.
Values:
------------------------------
-val - An instance of #<boolean>#.
-
+supplied? - An instance of #<boolean>#.
+See also:
+------------------------------
+- #unsupplied#
+- #unsupplied?#
Modified: trunk/documentation/gwydion/gdcore/text/name.table-definer.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.table-definer.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.table-definer.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,12 @@
Macro: table-definer
==============================
-A macro.
+Defines a constant binding in the current module and initializes it to a new table object. If the argument _type_ is supplied, the new table created is an instance of that type. Therefore type must be #<table># or a subclass thereof. If _type_ is not supplied, the new table created is an instance of a concrete subclass of #<table>#.
+
+: define table $colors :: <object-table>
+: = { #"red" => $red,
+: #"green" => $green,
+: #"blue" => $blue };
Exported from:
@@ -10,10 +15,16 @@
- #Module common-extensions#
-Definition:
+Macro call:
+------------------------------
+: define table (name) :: (type) = { (key) => (element), ... }
+
+
+Arguments:
------------------------------
-:
- list-style define macro
-
+name - A variable name.
+type - A class. Optional. Defaults to #<table>#.
+key - An expression for the key of the element.
+element - An expression for an element
Modified: trunk/documentation/gwydion/gdcore/text/name.table-protocol.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.table-protocol.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.table-protocol.txt Sun Feb 25 08:01:14 2007
@@ -36,14 +36,15 @@
Values:
------------------------------
test-function - An instance of #<function>#. Its signature is
- test-function(_key1_, _key2_) ⇒ _boolean_.
+ test-function( _key1_, _key2_ ) ⇒ _boolean_.
- _test-function_ is used to compare keys. It returns true if
the keys are members of the same equivalence class according
to the table's equivalence predicate.
hash-function - An instance of #<function>#. Its signature is
- hash-function(_key_) ⇒ (_id_, _state_)
+ hash-function( _key_, _initial-state_ ) ⇒
+ ( _id_, _result-state_ )
- _hash-function_ computes the hash code of the _key_, using the
hash function associated with the table's equivalence
Modified: trunk/documentation/gwydion/gdcore/text/name.thread-name.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.thread-name.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.thread-name.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Generic: thread-name
==============================
-A generic function.
+Returns the name of a thread.
Exported from:
@@ -17,12 +17,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+thread - An instance of #<thread>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+name-or-false - An instances of #<string># or #f.
Modified: trunk/documentation/gwydion/gdcore/text/name.thread-yield.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.thread-yield.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.thread-yield.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,10 @@
Function: thread-yield
==============================
-A function.
+Force the current thread to yield control to the part of the implementation
+responsible for scheduling threads. Doing so may have the effect of allowing
+other threads to run, and may be essential to avoid deadlock in a co-operative
+scheduling environment.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.unfound.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.unfound.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.unfound.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Function: unfound
==============================
-A function.
+Returns the unique "unfound" value, #$unfound#. Useful to indicate that a
+search has failed.
Exported from:
@@ -12,7 +13,11 @@
Values:
------------------------------
-val - An instance of <unfound-marker>.
-
+val - The value #$unfound#.
+See also:
+------------------------------
+- #found?#
+- #unfound?#
+- #$unfound#
Modified: trunk/documentation/gwydion/gdcore/text/name.unfoundQ.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.unfoundQ.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.unfoundQ.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Function: unfound?
==============================
-A function.
+Returns true if its argument is equal to the unique "unfound" value,
+#$unfound#, and false if it is not.
Exported from:
@@ -12,12 +13,16 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+object - An instance of #<object>#.
Values:
------------------------------
-val - An instance of #<boolean>#.
-
+unfound? - An instance of #<boolean>#.
+See also:
+------------------------------
+- #found?#
+- #$unfound#
+- #unfound#
Modified: trunk/documentation/gwydion/gdcore/text/name.unsupplied.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.unsupplied.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.unsupplied.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,8 @@
Function: unsupplied
==============================
-A function.
+Returns the unique "unsupplied" value. Useful as a default value for keyword
+arguments.
Exported from:
@@ -15,4 +16,7 @@
val - An instance of #<object>#.
-
+See also:
+------------------------------
+- #supplied?#
+- #unsupplied?#
Modified: trunk/documentation/gwydion/gdcore/text/name.unsuppliedQ.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.unsuppliedQ.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.unsuppliedQ.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,7 @@
Function: unsupplied?
==============================
-A function.
+Returns true if its argument is equal to the unique "unsupplied" value, and false if it is not.
Exported from:
@@ -20,4 +20,7 @@
val - An instance of #<boolean>#.
-
+See also:
+------------------------------
+- #supplied?#
+- #unsupplied#
Modified: trunk/documentation/gwydion/gdcore/text/name.values-hash.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.values-hash.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.values-hash.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,14 @@
Function: values-hash
==============================
-A function.
+Hashes the values passed to it. This function hashes every object in
+_arguments_ using _elem-hash-function_, and merges the resulting hash codes in
+order.
+
+The function _elem-hash-function_ must be suitable for use as a hash function.
+See page 123 of the _Dylan Reference Manual_.
+
+The _ordered_ keyword is passed on to #merge-hash-ids#.
Exported from:
@@ -11,15 +18,15 @@
Arguments:
------------------------------
-arg - An instance of #<function>#.
-arg - An instance of #<false>#.
-#rest more - Instances of #<object>#.
+elem-hash-function - An instance of #<function>#.
+initial-state - An instance of #<hash-state>#.
+#rest arguments - Instances of #<object>#.
Values:
------------------------------
-val - An instance of #<integer>#.
-val - An instance of #<false>#.
+hash-id - An instance of #<integer>#.
+result-state - An instance of #<hash-state>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.wait-for.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.wait-for.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.wait-for.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,15 @@
Generic: wait-for
==============================
-A generic function.
+Blocks until a synchronization object is available.
+
+This function is the basic blocking primitive of the Threads library. It
+blocks until _object_ is available and synchronization can be achieved, or the
+timeout interval has expired. A non-blocking synchronization may be attempted
+by specifying a timeout of zero. Individual methods may adjust the state of
+the synchronization object on synchronization. The function returns #t if
+synchronization is achieved before the timeout interval elapses; otherwise it
+returns #f.
Exported from:
@@ -17,13 +25,38 @@
Arguments:
------------------------------
-arg - An instance of #<synchronization>#.
-timeout: - An instance of type-union(<false>, <real>). The default is #f.
+object - An instance of #<synchronization>#.
+timeout: - An instance of type-union(<false>, <real>). Time-out interval. If
+ #f, the time-out interval never elapses. Otherwise, the #<real>#
+ value corresponds to the desired interval in seconds. The default
+ is #f.
Values:
------------------------------
-val - An instance of #<boolean>#.
+success - An instance of #<boolean>#.
+
+
+
+Method: wait-for
+==============================
+
+Claims a read-write lock, blocking if necessary. The behavior depends on the value of _mode_:
+#"read" - If there is a write lock, blocks until the lock becomes free. Then
+ claims the lock by incrementing its internal read-lock counter.
+#"write" - First waits until the lock becomes free, by blocking if necessary.
+ Then claims exclusive ownership of the lock in write mode. If the
+ claim is successful, this method returns true; otherwise it returns
+ false.
+
+Arguments:
+------------------------------
+object - An instance of #<read-write-lock>#.
+timeout: - An instance of type-union(<false>, <real>). Time-out interval. If
+ #f, the time-out interval never elapses. Otherwise, the #<real>#
+ value corresponds to the desired interval in seconds. The default
+ is #f.
+mode: - One of #"read", #"write". The default is #"read".
Modified: trunk/documentation/gwydion/gdcore/text/name.when.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.when.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.when.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,14 @@
Macro: when
==============================
-A macro.
+Executes a body if a test expression is true, and does nothing if the test is
+false. This macro behaves identically to Dylan's standard #if# statement
+macro, except that there is no alternative flow of execution when the test is
+false.
+
+: when (x < 0)
+: ~ x;
+: end;
Exported from:
@@ -10,10 +17,15 @@
- #Module common-extensions#
-Definition:
+Macro call:
------------------------------
-:
- statement macro
-
+: when ( (test) )
+: (consequent)
+: end when
+
+Arguments:
+------------------------------
+test - An expression.
+consequent - A body; a series of semicolon-separated expressions.
Modified: trunk/documentation/gwydion/gdcore/text/name.with-lock.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.with-lock.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.with-lock.txt Sun Feb 25 08:01:14 2007
@@ -1,7 +1,12 @@
Macro: with-lock
==============================
-A macro.
+Holds a lock while executing a body of code. If a _failure_ clause is
+supplied, then it will be evaluated and its values returned from #with-lock#
+if the lock cannot be claimed (because a timeout occurred). The default, if no
+_failure_ clause is supplied, is to signal an exception of class
+#<timeout-exceeded>#. If there is no failure, #with-lock# returns the results
+of evaluating the body.
Exported from:
@@ -10,10 +15,19 @@
- #Module threads#
-Definition:
+Macro call:
------------------------------
-:
- statement macro
-
+: with-lock ( (lock), (keys) )
+: (body)
+: failure (failure)
+: end
+
+
+Arguments:
+------------------------------
+lock - An instance of #<lock>#. The lock to claim.
+keys - Optional keyword parameters to #with-lock#.
+body - A series of semicolon-separated expressions.
+failure - An optional value to return if the _lock_ cannot be claimed.
More information about the chatter
mailing list