Changeset 4530 for trunk/manuals

Timestamp:

10/22/08 11:13:41 (3 months ago)

Author:

pmoura

Message:

Minor documentation improvements.

Location:

trunk/manuals/userman

Files:

• categories.html (modified) (2 diffs)
• events.html (modified) (2 diffs)
• installing.html (modified) (2 diffs)
• objects.html (modified) (2 diffs)
• predicates.html (modified) (5 diffs)
• protocols.html (modified) (1 diff)
• running.html (modified) (3 diffs)
• threads.html (modified) (3 diffs)

trunk/manuals/userman/categories.html

@@ -180 +180 @@
 <pre>:- dynamic.</pre>
 <p>
-The directive must precede any predicate directives or clauses. Please be aware that using dynamic code implies a performance hit when compared to  static code. We should only use dynamic categories when these need to be abolished during program execution.
+The directive must precede any predicate directives or clauses. Please be aware that using dynamic code results in a performance hit when compared to static code. We should only use dynamic categories when these need to be abolished during program execution.
 </p>
 
@@ -343 +343 @@
 :- end_object.</pre>
 <p>
-This alternative should only be used when the user knows a priori that the category predicates will not be specialized or redefined by descendant objects of the object importing the category. Its advantage is that, whenever possible, the Logtalk compiler will optimize the calls by using static binding (implies separate loading of the categories using the <code>reload(skip)</code> compiler flag). However, when static binding is not possible due to the lack of sufficient information at compilation time, the performance may be worse than calling the category predicate using a message to <em>self</em> due to the lack of a caching mechanism.
+This alternative should only be used when the user knows a priori that the category predicates will not be specialized or redefined by descendant objects of the object importing the category. Its advantage is that, whenever possible, the Logtalk compiler will optimize the calls by using static binding (requires separate loading of the categories using the <code>reload(skip)</code> compiler flag). However, when static binding is not possible due to the lack of sufficient information at compilation time, the performance may be worse than calling the category predicate using a message to <em>self</em> due to the lack of a caching mechanism.
 </p>
 

trunk/manuals/userman/events.html

@@ -132 +132 @@
 
 <p>
-Ideally, whenever there are several monitors defined for the same event, the calling order should not interfere with the result. However, this is not always possible. In the case of an event of type <code>before</code>, the failure of a monitor prevents a message from being sent and prevents the execution of the remaining monitors. In case of an event of type <code>after</code>, a monitor failure will force backtracking over message execution. Different orders of monitor activation can therefore lead to different results if the monitor actions imply object modifications unrecoverable in case of backtracking. Therefore, the order for monitor activation must be always taken as arbitrary. In effect, to suppose or to try to impose a specific sequence implies a global knowledge of an application dynamics, which is not always possible. Furthermore, that knowledge can reveal itself as incorrect if there is any changing in the execution conditions. Note that, given the independence between monitors, it does not make sense that a failure forces backtracking over the actions previously executed.
+Ideally, whenever there are several monitors defined for the same event, the calling order should not interfere with the result. However, this is not always possible. In the case of an event of type <code>before</code>, the failure of a monitor prevents a message from being sent and prevents the execution of the remaining monitors. In case of an event of type <code>after</code>, a monitor failure will force backtracking over message execution. Different orders of monitor activation can therefore lead to different results if the monitor actions imply object modifications unrecoverable in case of backtracking. Therefore, the order for monitor activation must be always taken as arbitrary. In effect, to assume or to try to impose a specific sequence requires a global knowledge of an application dynamics, which is not always possible. Furthermore, that knowledge can reveal itself as incorrect if there is any changing in the execution conditions. Note that, given the independence between monitors, it does not make sense that a failure forces backtracking over the actions previously executed.
 </p>
 
@@ -248 +248 @@
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: April 8, 2007</span>
+        <span>Last updated on: October 20, 2008</span>
     </div>
     <div class="navbottom">

trunk/manuals/userman/installing.html

@@ -188 +188 @@
 <dl>
     <dt><code>multifile_directive</code></dt>
-        <dd>Informs Logtalk if the Prolog compiler supports the ISO Prolog standard <code>multifile/1</code> predicate directive. Possible flag values are <code>unsupported</code> and <code>supported</code> (implies that multifile directives can be either static or dynamic).</dd>
+        <dd>Informs Logtalk if the Prolog compiler supports the ISO Prolog standard <code>multifile/1</code> predicate directive. Possible flag values are <code>unsupported</code> and <code>supported</code> (requires that multifile predicates can be either static or dynamic).</dd>
 </dl>
 <dl>
@@ -226 +226 @@
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: July 13, 2008</span>
+        <span>Last updated on: October 20, 2008</span>
     </div>
     <div class="navbottom">

trunk/manuals/userman/objects.html

@@ -318 +318 @@
 <pre>:- dynamic.</pre>
 <p>
-The directive must precede any predicate directives or clauses. Please be aware that using dynamic code implies a performance hit when compared to static code. We should only use dynamic objects when these need to be abolished during program execution. In addition, note that we can declare and define dynamic predicates within a static object.
+The directive must precede any predicate directives or clauses. Please be aware that using dynamic code results in a performance hit when compared to static code. We should only use dynamic objects when these need to be abolished during program execution. In addition, note that we can declare and define dynamic predicates within a static object.
 </p>
 
@@ -443 +443 @@
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: October 17, 2008</span>
+        <span>Last updated on: October 20, 2008</span>
     </div>
     <div class="navbottom">

trunk/manuals/userman/predicates.html

@@ -166 +166 @@
 When the same operators are used on several entities within the same source file, the corresponding directives must appear before any entity that uses them. However, this results in a global scope for the operators. If you prefer the operators to be local to the source file, just <em>undefine</em> them at the end of the file. For example:
 </p>
-<pre>:- op(400, xfx, implies).  % before any entity that uses the operator
+<pre>:- op(400, xfx, results).  % before any entity that uses the operator
 
 ...
 
-:- op(0, xfx, implies).    % after all entities that used the operator</pre>
+:- op(0, xfx, results).    % after all entities that used the operator</pre>
 
 <h3 id="predicates_uses">Uses directive</h3>
@@ -519 +519 @@
 yes</pre>
 <p>
-Note that the goals <code>self(Self)</code>, <code>sender(Sender)</code>, and <code>this(This)</code>, being translated to unifications with the clause head context arguments at compile time, are effectively removed from the clause body. This implies that a clause such as:
+Note that the goals <code>self(Self)</code>, <code>sender(Sender)</code>, and <code>this(This)</code>, being translated to unifications with the clause head context arguments at compile time, are effectively removed from the clause body. Therefore, a clause such as:
 </p>
 <pre>predicate(Arg) :-
@@ -548 +548 @@
 yes</pre>
 <p>
-The method <code>parameter/2</code> is only translated to a compile time unification when used inside objects with its first argument instantiated at compile time. When the first argument is not known at compile time, or when the method is used inside categories, its call implies a call to the built-in Prolog predicate <code>arg/3</code>. Nevertheless, note that calls to <code>parameter/2</code> from inside categories are inherently problematic: a category may be implemented by several objects, both parametric (with different number of parameters) and non-parametric. Care must be taken to ensure that a parametric object importing such a category match the interpretation of its parameters used in the category.
+The method <code>parameter/2</code> is only translated to a compile time unification when used inside objects with its first argument instantiated at compile time. When the first argument is not known at compile time, or when the method is used inside categories, its call results in a call to the built-in Prolog predicate <code>arg/3</code>. Nevertheless, note that calls to <code>parameter/2</code> from inside categories are inherently problematic: a category may be implemented by several objects, both parametric (with different number of parameters) and non-parametric. Care must be taken to ensure that a parametric object importing such a category match the interpretation of its parameters used in the category.
 </p>
 
@@ -620 +620 @@
 </p>
 <p>
-The predicate property <code>defined_in(Entity)</code> implies that definitions for the predicate are looked up in <code>Entity</code>. This does not necessarily implies that clauses for the predicate exist in <code>Entity</code>; the predicate can simply be false (closed world assumption).
+The predicate property <code>defined_in(Entity)</code> results in the definitions for the predicate being looked up in <code>Entity</code>. This does not necessarily implies that clauses for the predicate exist in <code>Entity</code>; the predicate can simply be false (closed world assumption).
 </p>
 <p>
@@ -679 +679 @@
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: October 11, 2008</span>
+        <span>Last updated on: October 20, 2008</span>
     </div>
     <div class="navbottom">

trunk/manuals/userman/protocols.html

@@ -125 +125 @@
 <pre>:- dynamic.</pre>
 <p>
-The directive must precede any predicate directives. Please be aware that using dynamic code implies a performance hit when compared to  static code. We should only use dynamic protocols when these need to be abolished during program execution.
+The directive must precede any predicate directives. Please be aware that using dynamic code results in a performance hit when compared to static code. We should only use dynamic protocols when these need to be abolished during program execution.
 </p>
 

trunk/manuals/userman/running.html

@@ -139 +139 @@
     <dl>
         <dt><code>xmldir(Directory)</code></dt>
-            <dd>Sets the directory to be used to store the automatically generated XML documenting files. The default value is <code>xml_docs</code>, a sub-directory of the source files directory. Use of this flag implies that the read-only flag <code>altdirs</code> be set to <code>on</code> (not supported in some back-end Prolog compilers).</dd>
+            <dd>Sets the directory to be used to store the automatically generated XML documenting files. The default value is <code>xml_docs</code>, a sub-directory of the source files directory. Use of this flag requires that the read-only flag <code>altdirs</code> be set to <code>on</code> (not supported in some back-end Prolog compilers).</dd>
     </dl>
     <dl>
@@ -194 +194 @@
     <dl>
         <dt><code>tmpdir(Directory)</code></dt>
-            <dd>Sets the directory to be used to store the temporary files generated when compiling Logtalk source files. The default value is <code>lgt_tmp</code>, a sub-directory of the source files directory. Use of this flag implies that the read-only flag <code>altdirs</code> be set to <code>on</code> (not supported in some back-end Prolog compilers).</dd>
+            <dd>Sets the directory to be used to store the temporary files generated when compiling Logtalk source files. The default value is <code>lgt_tmp</code>, a sub-directory of the source files directory. Use of this flag requires that the read-only flag <code>altdirs</code> be set to <code>on</code> (not supported in some back-end Prolog compilers).</dd>
     </dl>
 
@@ -200 +200 @@
 
 <p>
-As a general rule, reloading source files should never occur in production code and should be handled with care in development code. Reloading a Logtalk source file usually implies reloading the intermediate Prolog file that is generated by the Logtalk compiler. The problem is that there is no standard behavior for reloading Prolog files. For static predicates, almost all Prolog compilers replace the old definitions with the new ones. However, for dynamic predicates, the behavior depends on the Prolog compiler. Most compilers replace the old definitions but some of them simply append the new ones, which usually leads to trouble. See the compatibility notes for the back-end Prolog compiler you intend to use for more information. There is an additional potential problem when using multi-threading programming. Reloading a threaded object does not recreate from scratch its old message queue, which may still be in use (e.g. threads may be waiting on it).
+As a general rule, reloading source files should never occur in production code and should be handled with care in development code. Reloading a Logtalk source file usually requires reloading the intermediate Prolog file that is generated by the Logtalk compiler. The problem is that there is no standard behavior for reloading Prolog files. For static predicates, almost all Prolog compilers replace the old definitions with the new ones. However, for dynamic predicates, the behavior depends on the Prolog compiler. Most compilers replace the old definitions but some of them simply append the new ones, which usually leads to trouble. See the compatibility notes for the back-end Prolog compiler you intend to use for more information. There is an additional potential problem when using multi-threading programming. Reloading a threaded object does not recreate from scratch its old message queue, which may still be in use (e.g. threads may be waiting on it).
 </p>
 <p>

trunk/manuals/userman/threads.html

@@ -168 +168 @@
 </pre>
 <p>
-The call succeeds with no reply of the goal success, failure, or even exception ever being sent back to the object making the call. Note that this predicate implicitly implies a deterministic call of its argument.
+The call succeeds with no reply of the goal success, failure, or even exception ever being sent back to the object making the call. Note that this predicate implicitly performs a deterministic call of its argument.
 </p>
 
@@ -174 +174 @@
 
 <p>
-Proving a goal asynchronously using a new thread may lead to problems when the goal implies side-effects such as input/output operations or modifications to an object database. For example, if a new thread is started with the same goal before the first one finished its job, we may end up with mixed output, a corrupted database, or unexpected goal failures. In order to solve this problem, predicates (and grammar rule non-terminals) with side-effects can be declared as <em>synchronized</em> by using the <a title="Consult reference manual" href="../refman/directives/synchronized1.html"><code>synchronized/1</code></a> predicate directive. Proving a query to a synchronized predicate (or synchronized non-terminal) is internally protected by a mutex, thus allowing for easy thread synchronization. For example:
+Proving a goal asynchronously using a new thread may lead to problems when the goal results in side-effects such as input/output operations or modifications to an object database. For example, if a new thread is started with the same goal before the first one finished its job, we may end up with mixed output, a corrupted database, or unexpected goal failures. In order to solve this problem, predicates (and grammar rule non-terminals) with side-effects can be declared as <em>synchronized</em> by using the <a title="Consult reference manual" href="../refman/directives/synchronized1.html"><code>synchronized/1</code></a> predicate directive. Proving a query to a synchronized predicate (or synchronized non-terminal) is internally protected by a mutex, thus allowing for easy thread synchronization. For example:
 </p>
 <pre>:- synchronized(db_update/1).   % ensure thread synchronization
@@ -254 +254 @@
     <div class="copyright">
         <span>Copyright &copy; <a href="mailto:pmoura@logtalk.org">Paulo Moura</a> &mdash; <a href="http://logtalk.org">Logtalk.org</a></span><br/> 
-        <span>Last updated on: July 20, 2008</span>
+        <span>Last updated on: October 20, 2008</span>
     </div>
     <div class="navbottom">