[Gd-chatter] r10785 - in trunk/documentation/topic: concept/threads map/reference
housel at gwydiondylan.org
housel at gwydiondylan.org
Tue Jun 6 08:23:12 CEST 2006
Author: housel
Date: Tue Jun 6 08:23:11 2006
New Revision: 10785
Added:
trunk/documentation/topic/concept/threads/
trunk/documentation/topic/concept/threads/thread-atomicity.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-conditional-update.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-dynamic-binding.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-dynamic-environment.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-explicit-synchronization.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-ordering.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-safety-dylan.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-safety-general.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-safety.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-semantics.xml (contents, props changed)
trunk/documentation/topic/concept/threads/thread-variables.xml (contents, props changed)
trunk/documentation/topic/map/reference/
trunk/documentation/topic/map/reference/threads.ditamap (contents, props changed)
Log:
Bug: 7249
Adapt the beginning sections of the Threads chapter of the Core reference,
including a DITA map for the content.
Added: trunk/documentation/topic/concept/threads/thread-atomicity.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-atomicity.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,45 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd" []>
+<concept id="concept-thread-atomicity">
+ <title>Thread Atomicity</title>
+
+ <conbody>
+ <p>In general, the library guarantees that assignments to
+ slots and variables are atomic. That is, after an assignment, but
+ before synchronization, another thread will see either the old
+ value or the new value of the location. There is no possibility of
+ seeing a half-way state.</p>
+
+ <p>In some circumstances, when a slot or a variable is specialized
+ to be of a particularly constrained type, the Threads library does
+ not guarantee atomicity of assignments. Such a type may include a
+ subtype of <apiname><double-float></apiname> or a subtype of
+ <apiname><extended-float></apiname>. It may not include any
+ other type that is either defined in the current specification of
+ the Dylan language, or that could be created from standard
+ facilities provided by the current specification of the
+ language. This restriction of the atomicity guarantee is intended
+ to permit implementations to represent the values of such slots or
+ variables in a form which uses more space than a normal Dylan
+ value, for optimal efficiency.</p>
+
+ <p>For those cases where the implementation does not provide the atomicity
+ guarantee, the results of accessing a normal variable are undefined
+ if:</p>
+
+ <ul>
+ <li>The read could proceed in parallel with some write of the same
+ location</li>
+
+ <li>Two writes of the same location could have proceeded in parallel
+ since the last non-parallel write</li>
+ </ul>
+
+ <p>Two memory references <term>proceed in parallel</term> if they
+ are not explicitly sequentialized, either by being in a single
+ thread, or by explicit inter-thread synchronization.</p>
+
+ <p>Programmers should guard against the possibility of undefined values
+ by using explicit inter-thread synchronization. </p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-conditional-update.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-conditional-update.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,34 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-conditional-update">
+ <title>Conditional update</title>
+
+ <conbody>
+ <p>In addition to the synchronization primitives, the Dylan
+ threads facility provides a conditional update mechanism which is
+ not synchronized, but which tests whether the value in a variable
+ or slot has changed and atomically updates it if not. </p>
+
+ <p>By using conditional updates, a thread can confirm (or deny)
+ that there has been no interference from other threads, without
+ any need for a blocking operation. This is more efficient for
+ those circumstances where interference is not disastrous and it is
+ possible to recompute the update.</p>
+
+ <p>For example, a function which increments the value of a
+ variable might use a conditional update to store the new value
+ into place, in order to guarantee a numeric sequence for the
+ variable. In this example, the function might loop until the
+ conditional update has succeeded.</p>
+
+ <p>It is possible to achieve synchronization by looping until a
+ conditional update is successful, and then synchronizing side
+ effects. This is not recommended, because the busy-waiting state
+ during the loop may disallow other threads from running. Normally,
+ conditional update should be used only when it is expected to
+ succeed. If it is likely that the conditional update might fail
+ multiple times around the loop, then either the number of times
+ around the loop should be limited, or a blocking function from the
+ Threads library should be used within the loop.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-dynamic-binding.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-dynamic-binding.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,30 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-variables">
+ <title>Dynamic binding</title>
+
+ <conbody>
+ <p>The Threads library exports a macro for dynamic binding. A
+ <term>binding</term> is a mapping between a variable and a
+ <term>value-cell</term> which holds the variable’s value. A
+ <i>dynamic </i> binding is a binding which has dynamic extent, and
+ shadows any outermost bindings. Dynamic bindings can be considered
+ to be a property of the dynamic environment. </p>
+
+ <p>Thread variables can have new dynamic bindings created for them
+ with the macro <codeph>dynamic-bind</codeph>, FIXME page
+ 104. Thread variables inherently have thread-local bindings, so it
+ is possible to re-bind a thread variable dynamically using the
+ Dylan construct <codeph>block</codeph>
+ ... <codeph>cleanup</codeph>. The <codeph>dynamic-bind</codeph>
+ macro can be implemented in this way.</p>
+
+ <p>The thread-local nature of dynamically bindable variables may
+ not be optimal for all problem domains. For instance a shared,
+ global, outermost binding may be desirable, or alternatively, a
+ thread may want to inherit current bindings from the parent thread
+ at creation time, giving a “fork”-type model of state
+ inheritance. These alternatives are not pursued in this library,
+ but they might be an interesting area for future research.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-dynamic-environment.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-dynamic-environment.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,38 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-dynamic-environment">
+ <title>The Dynamic Environment</title>
+
+ <conbody>
+ <p>Dylan has an implicit notion of a <term>dynamic
+ environment</term>, corresponding to language constructs with
+ <term>dynamic extent</term>. For example, the
+ <apiname>block</apiname> construct can introduce
+ <i>cleanup-clauses</i>, and the <i>body</i> of the block is
+ executed in a dynamic environment in which those cleanup-clauses
+ are active. <term>Handlers</term> and <term>exit procedures
+ </term> are other examples of language features related to the
+ dynamic environment. </p>
+
+ <p>The dynamic environment is defined to be thread-local. When a new
+ thread is created, it starts with a fresh dynamic environment. It is
+ an error to attempt to use a handler or a non-local exit function belonging
+ to another thread. It is impossible to use an unwind-protect cleanup
+ from another thread.</p>
+
+ <p>Although the binding of condition handlers only affects the
+ dynamic environment of the current thread, unhandled conditions
+ are passed to the global generic function
+ <apiname>default-handler</apiname> . This function might
+ <term>call the debugger</term>. The threads facility does not
+ define what calling the debugger means.</p>
+
+ <p>Note that in Dylan, unlike in C and C++, <i>lexical</i>
+ variables (that is local, or <codeph>let</codeph>-bound variables)
+ have indefinite extent—that is, have a lifetime independent
+ of the function or block in which they were created—and are
+ not bound in the dynamic environment. Because those variables are
+ in general potentially global, you may need to explicitly
+ synchronize accesses to them.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-explicit-synchronization.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-explicit-synchronization.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,33 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-explicit-synchronization">
+ <title>Explicit synchronization</title>
+
+ <conbody>
+ <p>The Dylan threads facility provides low-level synchronization
+ functions which control the ordering of operations with respect to
+ other threads, and control when the side effects that have been
+ performed within one thread become visible within other
+ threads.</p>
+
+ <p>At a higher level, the threads facility provides a variety of
+ synchronization facilities, described below. These facilities
+ include mutual-exclusion locks, semaphores and notifications. Each
+ facility guarantees that when synchronization has been achieved,
+ all the side effects of another thread are visible, at least up to
+ the point where that other thread last released the
+ synchronization facility. </p>
+
+ <p>An appropriate synchronization must be used to guard side-effects
+ on state if there is any possibility of those side-effects either being
+ corrupted by another thread or corrupting another thread. For example,
+ a function which assigns to two slots of an object may require the use
+ of a lock to guarantee that other threads never observe the object in
+ a partly updated state.</p>
+
+ <p>It is up to library designers to document when synchronization is
+ not performed internally, and when synchronization protocols must be
+ used by clients. The implications for the Dylan library, and some other
+ low-level libraries, are discussed FIXME in Section 4.3 on page 72.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-ordering.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-ordering.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,27 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../dtd/concept.dtd" []>
+<concept id="concept-thread-ordering">
+ <title>Ordering</title>
+
+ <conbody>
+ <p>The ordering of visibility of side effects performed in other
+ threads is undefined, unless explicit synchronization is
+ used. Implementations of the library may guarantee that the
+ visibility of side-effects performed by another thread is ordered
+ according to the control flow of the other thread (<term>strong
+ ordering</term>), but multi-processor implementations might not be
+ strongly ordered. Portable code should not assume strong ordering,
+ and should use explicit synchronization where the order of side
+ effects is important. There is currently no library introspection
+ facility to determine if the implementation is strongly or weakly
+ ordered.</p>
+
+ <p>Because of the possibility of weak ordering, the compiler is
+ free to assume that the effects of other threads may be ignored
+ between explicit synchronization points, and it may perform any
+ optimizations which preserve the semantics of a single-thread
+ model regardless of their effects on other threads—for
+ example, common sub-expression elimination, or changing the order
+ of evaluation.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-safety-dylan.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-safety-dylan.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,34 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-safety-general">
+ <title>Effects of Thread Safety on the Dylan Library</title>
+
+ <conbody>
+ <p>The definition of the Dylan library is not changed with the
+ addition of the Dylan threads facility. The implementation ensures
+ that all hidden global state (such as the symbol table and any
+ generic function caches) is implicitly synchronized. Those
+ functions in the Dylan library which are defined to modify the
+ state of objects are not defined to provide implicit
+ synchronization. However, implementations are expected to ensure
+ that synchronization bugs in Dylan programs will not cause obscure
+ errors that cannot be explained in terms of the semantics of Dylan
+ language constructs.</p>
+
+ <p>The library guarantees that <apiname>element</apiname> and
+ <apiname>element-setter</apiname> will be atomic for all of Dylan’s
+ non-stretchy built-in collection classes, and for
+ <apiname><table></apiname>, except for subclasses of
+ <apiname><string></apiname>, and limited collections where
+ the elements are constrained to be either of a type for which
+ slots and variables do not guarantee atomicity (see FIXME Section 4.2.1
+ on page 67) or a subtype of <apiname><character></apiname>,
+ or of a proper subtype of <apiname><integer></apiname>. This
+ design is intended to permit implementations to use efficient
+ representations for element values, which use either more or less
+ space than a normal Dylan value. It is undefined whether any of
+ the other standard Dylan functions are atomic. Where atomicity is
+ not guaranteed, clients should guard against unexpected behavior
+ by using explicit synchronization, as appropriate.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-safety-general.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-safety-general.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,30 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-safety-general">
+ <title>General Thread Safety Requirements</title>
+
+ <conbody>
+ <p>A library’s designer is responsible for documenting which
+ features of the library offer built-in synchronization and which
+ do not. While there is no definitive rule that can assist
+ designers in this documentation, the following guidelines may be
+ useful.</p>
+
+ <p>If a client of the library forgets to use a synchronization
+ feature when one is necessary, the library designer should ensure
+ that the effect of the lack of synchronization is limited to a
+ small unit—probably a single object. In cases where the
+ designer cannot guarantee that the effect will be limited, the
+ library should either implement the synchronization internally, or
+ provide a macro for clients to use instead.</p>
+
+ <p>Library implementors must ensure that the library provides
+ implicit synchronization for any hidden global state which is
+ maintained by the library. Library designers may choose whether
+ the library should offer implicit synchronization of the state of
+ objects managed by the library. The interface is more convenient
+ if the synchronization is implicit, but it may be more efficient
+ to rely on explicit synchronization by the client. Library
+ designers should always document the choice they make.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-safety.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-safety.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,13 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-safety">
+ <title>Thread safety in client libraries</title>
+
+ <conbody>
+ <p>If an application uses multiple threads, then there may be
+ thread safety requirements for any library that can be called
+ simultaneously by multiple threads, even if the called library
+ does not use the Dylan threads facility directly.</p>
+ </conbody>
+</concept>
+
Added: trunk/documentation/topic/concept/threads/thread-semantics.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-semantics.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,17 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-semantics">
+ <title>Multi-thread semantics</title>
+
+ <conbody>
+ <p>The Dylan Threads facility provides multiple threads of control
+ within a single space of objects and module variables. Each thread
+ runs in its own independent stack. The mechanism by which the
+ threads are scheduled is not specified, and it is not possible to
+ determine how the execution of instructions by different threads
+ will be interleaved. No mechanism is provided to call a function
+ on an existing thread other than the current thread. Neither is
+ there a mechanism to signal an exception on a thread other than
+ the current thread.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/concept/threads/thread-variables.xml
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/concept/threads/thread-variables.xml Tue Jun 6 08:23:11 2006
@@ -0,0 +1,25 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "../../dtd/concept.dtd">
+<concept id="concept-thread-variables">
+ <title>Thread variables</title>
+
+ <conbody>
+ <p>The Dylan threads facility provides a new type of variable: a
+ <term>thread</term> variable, also known as a
+ <term>thread-local</term> variable. These variables are similar
+ to normal module variables in the sense that they are visible
+ according to the same scoping rules and have the same semantics
+ in a single-threaded program. However, in contrast to a normal
+ variable, assignments to a thread variable in one thread are not
+ visible when evaluating the variable in another thread.</p>
+
+ <p>Whenever a thread is created, the value of each thread variable
+ is initialized to a thread-independent value resulting from a
+ once-only evaluation of the initialization expression of the
+ thread variable definition.</p>
+
+ <p>See FIXME page 103 for details of the
+ <codeph>thread</codeph> adjective to <codeph>define
+ variable</codeph>.</p>
+ </conbody>
+</concept>
Added: trunk/documentation/topic/map/reference/threads.ditamap
==============================================================================
--- (empty file)
+++ trunk/documentation/topic/map/reference/threads.ditamap Tue Jun 6 08:23:11 2006
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "../dtd/map.dtd">
+<map title="The Dylan Threads Facility">
+ <topicref navtitle="Introduction" href="../../reference/lib/common-dylan/threads.xml" />
+ <topicref href="../../concept/threads/thread-semantics.xml">
+ <topicref href="../../concept/threads/thread-atomicity.xml" />
+ <topicref href="../../concept/threads/thread-ordering.xml" />
+ <topicref href="../../concept/threads/thread-explicit-synchronization.xml" />
+ <topicref href="../../concept/threads/thread-conditional-update.xml" />
+ <topicref href="../../concept/threads/thread-dynamic-environment.xml" />
+ <topicref href="../../concept/threads/thread-variables.xml" />
+ <topicref href="../../concept/threads/thread-dynamic-binding.xml" />
+ </topicref>
+ <topicref href="../../concept/threads/thread-safety.xml">
+ <topicref href="../../concept/threads/thread-safety-general.xml" />
+ <topicref href="../../concept/threads/thread-safety-dylan.xml" />
+ </topicref>
+</map>
More information about the chatter
mailing list