Home | History | Annotate | Download | only in base
      1 /*
      2  * libjingle
      3  * Copyright 2004--2006, Google Inc.
      4  *
      5  * Redistribution and use in source and binary forms, with or without
      6  * modification, are permitted provided that the following conditions are met:
      7  *
      8  *  1. Redistributions of source code must retain the above copyright notice,
      9  *     this list of conditions and the following disclaimer.
     10  *  2. Redistributions in binary form must reproduce the above copyright notice,
     11  *     this list of conditions and the following disclaimer in the documentation
     12  *     and/or other materials provided with the distribution.
     13  *  3. The name of the author may not be used to endorse or promote products
     14  *     derived from this software without specific prior written permission.
     15  *
     16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
     17  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     18  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
     19  * EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
     20  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
     21  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
     22  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
     23  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
     24  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
     25  * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
     26  */
     27 
     28 #ifndef TALK_BASE_TASK_H__
     29 #define TALK_BASE_TASK_H__
     30 
     31 #include <string>
     32 #include "talk/base/basictypes.h"
     33 #include "talk/base/scoped_ptr.h"
     34 #include "talk/base/sigslot.h"
     35 #include "talk/base/taskparent.h"
     36 
     37 /////////////////////////////////////////////////////////////////////
     38 //
     39 // TASK
     40 //
     41 /////////////////////////////////////////////////////////////////////
     42 //
     43 // Task is a state machine infrastructure.  States are pushed forward by
     44 // pushing forwards a TaskRunner that holds on to all Tasks.  The purpose
     45 // of Task is threefold:
     46 //
     47 // (1) It manages ongoing work on the UI thread.  Multitasking without
     48 // threads, keeping it easy, keeping it real. :-)  It does this by
     49 // organizing a set of states for each task.  When you return from your
     50 // Process*() function, you return an integer for the next state.  You do
     51 // not go onto the next state yourself.  Every time you enter a state,
     52 // you check to see if you can do anything yet.  If not, you return
     53 // STATE_BLOCKED.  If you _could_ do anything, do not return
     54 // STATE_BLOCKED - even if you end up in the same state, return
     55 // STATE_mysamestate.  When you are done, return STATE_DONE and then the
     56 // task will self-delete sometime afterwards.
     57 //
     58 // (2) It helps you avoid all those reentrancy problems when you chain
     59 // too many triggers on one thread.  Basically if you want to tell a task
     60 // to process something for you, you feed your task some information and
     61 // then you Wake() it.  Don't tell it to process it right away.  If it
     62 // might be working on something as you send it information, you may want
     63 // to have a queue in the task.
     64 //
     65 // (3) Finally it helps manage parent tasks and children.  If a parent
     66 // task gets aborted, all the children tasks are too.  The nice thing
     67 // about this, for example, is if you have one parent task that
     68 // represents, say, and Xmpp connection, then you can spawn a whole bunch
     69 // of infinite lifetime child tasks and now worry about cleaning them up.
     70 //  When the parent task goes to STATE_DONE, the task engine will make
     71 // sure all those children are aborted and get deleted.
     72 //
     73 // Notice that Task has a few built-in states, e.g.,
     74 //
     75 // STATE_INIT - the task isn't running yet
     76 // STATE_START - the task is in its first state
     77 // STATE_RESPONSE - the task is in its second state
     78 // STATE_DONE - the task is done
     79 //
     80 // STATE_ERROR - indicates an error - we should audit the error code in
     81 // light of any usage of it to see if it should be improved.  When I
     82 // first put down the task stuff I didn't have a good sense of what was
     83 // needed for Abort and Error, and now the subclasses of Task will ground
     84 // the design in a stronger way.
     85 //
     86 // STATE_NEXT - the first undefined state number.  (like WM_USER) - you
     87 // can start defining more task states there.
     88 //
     89 // When you define more task states, just override Process(int state) and
     90 // add your own switch statement.  If you want to delegate to
     91 // Task::Process, you can effectively delegate to its switch statement.
     92 // No fancy method pointers or such - this is all just pretty low tech,
     93 // easy to debug, and fast.
     94 //
     95 // Also notice that Task has some primitive built-in timeout functionality.
     96 //
     97 // A timeout is defined as "the task stays in STATE_BLOCKED longer than
     98 // timeout_seconds_."
     99 //
    100 // Descendant classes can override this behavior by calling the
    101 // various protected methods to change the timeout behavior.  For
    102 // instance, a descendand might call SuspendTimeout() when it knows
    103 // that it isn't waiting for anything that might timeout, but isn't
    104 // yet in the STATE_DONE state.
    105 //
    106 
    107 namespace talk_base {
    108 
    109 // Executes a sequence of steps
    110 class Task : public TaskParent {
    111  public:
    112   Task(TaskParent *parent);
    113   virtual ~Task();
    114 
    115   int32 unique_id() { return unique_id_; }
    116 
    117   void Start();
    118   void Step();
    119   int GetState() const { return state_; }
    120   bool HasError() const { return (GetState() == STATE_ERROR); }
    121   bool Blocked() const { return blocked_; }
    122   bool IsDone() const { return done_; }
    123   int64 ElapsedTime();
    124 
    125   // Called from outside to stop task without any more callbacks
    126   void Abort(bool nowake = false);
    127 
    128   bool TimedOut();
    129 
    130   int64 timeout_time() const { return timeout_time_; }
    131   int timeout_seconds() const { return timeout_seconds_; }
    132   void set_timeout_seconds(int timeout_seconds);
    133 
    134   sigslot::signal0<> SignalTimeout;
    135 
    136   // Called inside the task to signal that the task may be unblocked
    137   void Wake();
    138 
    139  protected:
    140 
    141   enum {
    142     STATE_BLOCKED = -1,
    143     STATE_INIT = 0,
    144     STATE_START = 1,
    145     STATE_DONE = 2,
    146     STATE_ERROR = 3,
    147     STATE_RESPONSE = 4,
    148     STATE_NEXT = 5,  // Subclasses which need more states start here and higher
    149   };
    150 
    151   // Called inside to advise that the task should wake and signal an error
    152   void Error();
    153 
    154   int64 CurrentTime();
    155 
    156   virtual std::string GetStateName(int state) const;
    157   virtual int Process(int state);
    158   virtual void Stop();
    159   virtual int ProcessStart() = 0;
    160   virtual int ProcessResponse() { return STATE_DONE; }
    161 
    162   void ResetTimeout();
    163   void ClearTimeout();
    164 
    165   void SuspendTimeout();
    166   void ResumeTimeout();
    167 
    168  protected:
    169   virtual int OnTimeout() {
    170     // by default, we are finished after timing out
    171     return STATE_DONE;
    172   }
    173 
    174  private:
    175   void Done();
    176 
    177   int state_;
    178   bool blocked_;
    179   bool done_;
    180   bool aborted_;
    181   bool busy_;
    182   bool error_;
    183   int64 start_time_;
    184   int64 timeout_time_;
    185   int timeout_seconds_;
    186   bool timeout_suspended_;
    187   int32 unique_id_;
    188 
    189   static int32 unique_id_seed_;
    190 };
    191 
    192 }  // namespace talk_base
    193 
    194 #endif  // TALK_BASE_TASK_H__
    195