Upgrade to ExtJS 3.1.0 - Released 12/16/2009
[extjs.git] / docs / source / TaskMgr.html
1 <html>\r
2 <head>\r
3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
4   <title>The source code</title>\r
5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
7 </head>\r
8 <body  onload="prettyPrint();">\r
9     <pre class="prettyprint lang-js"><div id="cls-Ext.util.TaskRunner"></div>/**
10  * @class Ext.util.TaskRunner
11  * Provides the ability to execute one or more arbitrary tasks in a multithreaded
12  * manner.  Generally, you can use the singleton {@link Ext.TaskMgr} instead, but
13  * if needed, you can create separate instances of TaskRunner.  Any number of
14  * separate tasks can be started at any time and will run independently of each
15  * other. Example usage:
16  * <pre><code>
17 // Start a simple clock task that updates a div once per second
18 var updateClock = function(){
19     Ext.fly('clock').update(new Date().format('g:i:s A'));
20
21 var task = {
22     run: updateClock,
23     interval: 1000 //1 second
24 }
25 var runner = new Ext.util.TaskRunner();
26 runner.start(task);
27
28 // equivalent using TaskMgr
29 Ext.TaskMgr.start({
30     run: updateClock,
31     interval: 1000
32 });
33
34  * </code></pre>
35  * Also see {@link Ext.util.DelayedTask}. 
36  * 
37  * @constructor
38  * @param {Number} interval (optional) The minimum precision in milliseconds supported by this TaskRunner instance
39  * (defaults to 10)
40  */
41 Ext.util.TaskRunner = function(interval){
42     interval = interval || 10;
43     var tasks = [], 
44         removeQueue = [],
45         id = 0,
46         running = false,
47
48         // private
49         stopThread = function(){
50                 running = false;
51                 clearInterval(id);
52                 id = 0;
53             },
54
55         // private
56         startThread = function(){
57                 if(!running){
58                     running = true;
59                     id = setInterval(runTasks, interval);
60                 }
61             },
62
63         // private
64         removeTask = function(t){
65                 removeQueue.push(t);
66                 if(t.onStop){
67                     t.onStop.apply(t.scope || t);
68                 }
69             },
70             
71         // private
72         runTasks = function(){
73                 var rqLen = removeQueue.length,
74                         now = new Date().getTime();                                             
75             
76                 if(rqLen > 0){
77                     for(var i = 0; i < rqLen; i++){
78                         tasks.remove(removeQueue[i]);
79                     }
80                     removeQueue = [];
81                     if(tasks.length < 1){
82                         stopThread();
83                         return;
84                     }
85                 }               
86                 for(var i = 0, t, itime, rt, len = tasks.length; i < len; ++i){
87                     t = tasks[i];
88                     itime = now - t.taskRunTime;
89                     if(t.interval <= itime){
90                         rt = t.run.apply(t.scope || t, t.args || [++t.taskRunCount]);
91                         t.taskRunTime = now;
92                         if(rt === false || t.taskRunCount === t.repeat){
93                             removeTask(t);
94                             return;
95                         }
96                     }
97                     if(t.duration && t.duration <= (now - t.taskStartTime)){
98                         removeTask(t);
99                     }
100                 }
101             };
102
103     <div id="method-Ext.util.TaskRunner-start"></div>/**
104      * Starts a new task.
105      * @method start
106      * @param {Object} task A config object that supports the following properties:<ul>
107      * <li><code>run</code> : Function<div class="sub-desc">The function to execute each time the task is run. The
108      * function will be called at each interval and passed the <code>args</code> argument if specified.  If a
109      * particular scope is required, be sure to specify it using the <code>scope</code> argument.</div></li>
110      * <li><code>interval</code> : Number<div class="sub-desc">The frequency in milliseconds with which the task
111      * should be executed.</div></li>
112      * <li><code>args</code> : Array<div class="sub-desc">(optional) An array of arguments to be passed to the function
113      * specified by <code>run</code>.</div></li>
114      * <li><code>scope</code> : Object<div class="sub-desc">(optional) The scope (<tt>this</tt> reference) in which to execute the
115      * <code>run</code> function. Defaults to the task config object.</div></li>
116      * <li><code>duration</code> : Number<div class="sub-desc">(optional) The length of time in milliseconds to execute
117      * the task before stopping automatically (defaults to indefinite).</div></li>
118      * <li><code>repeat</code> : Number<div class="sub-desc">(optional) The number of times to execute the task before
119      * stopping automatically (defaults to indefinite).</div></li>
120      * </ul>
121      * @return {Object} The task
122      */
123     this.start = function(task){
124         tasks.push(task);
125         task.taskStartTime = new Date().getTime();
126         task.taskRunTime = 0;
127         task.taskRunCount = 0;
128         startThread();
129         return task;
130     };
131
132     <div id="method-Ext.util.TaskRunner-stop"></div>/**
133      * Stops an existing running task.
134      * @method stop
135      * @param {Object} task The task to stop
136      * @return {Object} The task
137      */
138     this.stop = function(task){
139         removeTask(task);
140         return task;
141     };
142
143     <div id="method-Ext.util.TaskRunner-stopAll"></div>/**
144      * Stops all tasks that are currently running.
145      * @method stopAll
146      */
147     this.stopAll = function(){
148         stopThread();
149         for(var i = 0, len = tasks.length; i < len; i++){
150             if(tasks[i].onStop){
151                 tasks[i].onStop();
152             }
153         }
154         tasks = [];
155         removeQueue = [];
156     };
157 };
158
159 <div id="cls-Ext.TaskMgr"></div>/**
160  * @class Ext.TaskMgr
161  * @extends Ext.util.TaskRunner
162  * A static {@link Ext.util.TaskRunner} instance that can be used to start and stop arbitrary tasks.  See
163  * {@link Ext.util.TaskRunner} for supported methods and task config properties.
164  * <pre><code>
165 // Start a simple clock task that updates a div once per second
166 var task = {
167     run: function(){
168         Ext.fly('clock').update(new Date().format('g:i:s A'));
169     },
170     interval: 1000 //1 second
171 }
172 Ext.TaskMgr.start(task);
173 </code></pre>
174  * @singleton
175  */
176 Ext.TaskMgr = new Ext.util.TaskRunner();</pre>    \r
177 </body>\r
178 </html>