Revision: 4020
http://vexi.svn.sourceforge.net/vexi/?rev=4020&view=rev
Author: clrg
Date: 2011-02-04 19:51:42 +0000 (Fri, 04 Feb 2011)
Log Message:
-----------
More docs
Modified Paths:
--------------
trunk/org.vexi-core.main/src/main/jpp/org/vexi/core/Vexi.jpp
Modified: trunk/org.vexi-core.main/src/main/jpp/org/vexi/core/Vexi.jpp
===================================================================
--- trunk/org.vexi-core.main/src/main/jpp/org/vexi/core/Vexi.jpp
2011-02-04 16:57:05 UTC (rev 4019)
+++ trunk/org.vexi-core.main/src/main/jpp/org/vexi/core/Vexi.jpp
2011-02-04 19:51:42 UTC (rev 4020)
@@ -206,29 +206,49 @@
/*@PAGE(concept=Threading)
*
- * <p>All vexiscript threads execute synchronously. This is to say that at any
one time only ever
- * at most one vexiscript is running. This is a <i>powerful limitation</i> as
it avoids the
+ * <p>All vexiscript threads execute synchronously. This is to say that at
any one time only ever
+ * at most one vexiscript is running. This is a <i>powerful limitation</i> as
it avoids the
* possibility of concurrent access to javascript objects.</p>
*
- * <p>The threading is co-operatively multi-tasked. Long running threads
should yield at regular
- * intervals to prevent unresponsiveness. This will either happen when
performing a background
- * process (such as an rpc call) where a wait can be expected for a response,
or can be done
- * by explicitly calling yield().</p>
+ * <p>The threading is co-operatively multi-tasked. Long running threads
should yield at regular
+ * intervals to prevent unresponsiveness. This will either happen
automatically when performing
+ * a background process (such as an RPC call) where a wait can be expected for
a response, or can
+ * be done by explicitly calling <code>vexi.thread.yield()</code>.</p>
*
- * <p>Threads are round-robin scheduled (i.e in a FIFO queue) and when they
yield they will
- * start again at the back of the queue.</p>
+ * <p>There are two types of thread in vexiscript; the
‘foreground’ thread —
+ * which executes layout and event traps — and ‘background’
threads.
*
- * <p>To create a thread simply put a function to the <code>vexi.thread</code>
property.</p>
+ * <h3>The Foreground Thread</h3>
*
+ * <p>The foreground thread is implicit. Code in the foreground thread is
typically
+ * invoked by layout-related traps or input events.</p>
+ *
+ * <p>A limitation of the foreground thread is that no blocking operations may
be performed
+ * and subsequently calls to <code>vexi.thread.sleep()</code> and
+ * <code>vexi.thread.yield()</code> will cause an exception.</p>
+ *
+ * <p>The foreground thread is executed inbetween every execution of a
background thread,
+ * as part of the core layout cycle (known as <i>reflow</i>).</p>
+ *
+ * <h3>Background Threads</h3>
+ *
+ * <p>A background thread is an explicitly created thread that may perform
blocking operations
+ * such as RPC calls, or call <code>vexi.thread.sleep()</code> or
+ * <code>vexi.thread.yield()</code> (in constrast with the foreground thread).
+ *
+ * <p>To create a background thread simply put a function to the
<code>vexi.thread</code>
+ * property:</p>
+ *
* <pre>vexi.thread = function() {
* // code here runs in a background thread
- * thisbox.name = vexi.net.rpc.xml(server_url).getName();
*}</pre>
*
- * <p>All threads created in this manner are <i>background</i> threads, which
means they may
- * perform blocking operations such as rpc calls, or call sleep() or yield().
This is in contrast
- * with the <i>foreground</i> thread, which is the thread which executes
events traps.</p>
+ * <p>This places the function in the thread queue, and it will be
automatically invoked. To
+ * remove a function from the thread queue, complete the function (i.e.
<code>return</code>).</p>
*
+ * <p>Background threads are round-robin scheduled (i.e in a FIFO queue) and
when they yield they
+ * will start again at the back of the queue.</p>
+ *
* */
@@ -291,13 +311,13 @@
public JS get(JS name) throws JSExn {
// FEATURE: Preprocessor hack to generate specialized JS instances
(avoid all this string concatenation)
//#switch(JSU.toString(name))
- /*@PAGE(varname=vexi,humanname=Vexi System Object)
+ /*@PAGE(varname=vexi,humanname=The Vexi Object)
*
- * <p>The vexi system object. It is always accessible from vexiscript
using the
+ * <p>The global Vexi object. It is always accessible from vexiscript
using the
* <code>vexi</code> keyword.</p>
*
- * <p>The root namespace is accessible using the [""] property. That
is, a template
- * located at dir/subdir/tmpl.t would be accessible as:</p>
+ * <p>The root namespace is accessible using the <code>[""]</code>
property. That is, a template
+ * located at ‘dir/subdir/tmpl.t’ would be accessible
as:</p>
*
* <pre>vexi..dir.subdir.tmpl</pre>
* */
@@ -325,7 +345,7 @@
case "ui.mouse": return getSub(name);
case "ui.screen": return getSub(name);
- /* The version of the current vexi core
+ /* The version of the current Vexi core
* @type(String)
* @initial_value(varies,code=false) */
case "about.version": return JSU.S("MODULE_VERSION");
@@ -336,7 +356,7 @@
* @nofollow */
case "biscuits": return Resources.biscuits;
- /* Ensures a resource is properly loaded and accessible.
+ /* Ensures a resource is properly loaded and accessible
* @return(null) */
case "bless": return METHOD;
This was sent by the SourceForge.net collaborative development platform, the
world's largest Open Source development site.
------------------------------------------------------------------------------
The modern datacenter depends on network connectivity to access resources
and provide services. The best practices for maximizing a physical server's
connectivity to a physical network are well understood - see how these
rules translate into the virtual world?
http://p.sf.net/sfu/oracle-sfdevnlfb
_______________________________________________
Vexi-svn mailing list
Vexi-svn@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/vexi-svn
