HelpSource/Classes/SkipJack.schelp

   1 class:: SkipJack
   2 summary:: A utility for background tasks that survive cmd-period
   3 categories:: Scheduling, Libraries>JITLib>GUI
   4 related:: Classes/CmdPeriod
   5
   6 Description::
   7 SkipJack is a utility to run a function in the background repeatedly, that survive cmd-period.
   8
   9 A typical use is with a window displaying the state of some objects every now and then. (This is better in some cases than
  10 updating the GUI at every change. If the changes happen fast, you don't choke your CPU on gui updating.)
  11
  12 But SkipJack is useful whenever you need a periodic function to run in the background and not go away if the user hits cmd-period.
  13
  14 ClassMethods::
  15
  16 private::initClass
  17
  18 method::new
  19
  20 argument::updateFunc
  21 A link::Classes/Function:: to repeat in the background.
  22
  23 argument::dt
  24 The time interval at which to repeat. It can also be a stream or a function that returns a number.
  25
  26 argument::stopTest
  27 A test whether to stop the task now. Usually a Function.
  28
  29 argument::name
  30 A name for this skipjack. Used for posting information and in the link::#*stop:: classmethod.
  31
  32 argument::clock
  33 The clock that plays the task. Default is link::Classes/AppClock::, so SkipJack can call GUI primitives. If you need more precise timing, you can supply your own clock, and use defer only where necessary.
  34
  35 argument::autostart
  36 When true (default) SkipJack starts automatically as it is created.
  37
  38 method:: stop
  39 Stop a skipjack by name.
  40
  41 method:: stopAll
  42 Stop all skipjacks.
  43
  44 method:: defaultClock
  45 The default clock (AppClock)
  46
  47 method:: verbose
  48 When true, SkipJack posts messages when it starts, stops or restarts.
  49
  50 method:: all
  51 The global set of all skipjacks.
  52
  53 Instancemethods::
  54 private:: cmdPeriod
  55
  56 method:: dt
  57 Get or set the time interval.
  58
  59 method:: task
  60 The internal Routine that wraps updateFunc.
  61
  62 method:: name
  63 The name of this skipjack.
  64
  65 method:: stopTest
  66 The current stopTest. (see argument in link::#*new:: )
  67
  68 method:: start
  69 Start this skipjack.
  70
  71 method:: play
  72 Same as code::start::
  73
  74 method:: stop
  75 Stop this skipjack.
  76
  77 method:: clock
  78 Get or set the clock used. This will only be updated when the skipjack restarts.
  79
  80 method:: updateFunc
  81 The updateFunc set by the argument to link::#*new::
  82
  83 Examples::
  84 Simple example:
  85 code::
  86 w = SkipJack({ "watch...".postln; }, 0.5, name: "test");
  87 SkipJack.verbose = true;    // post stop/wakeup logs
  88
  89 w.stop;
  90 w.start;
  91
  92 //      now try to stop with cmd-. : SkipJack always restarts itself.
  93 thisProcess.stop;
  94
  95 w.stop;
  96 ::
  97
  98 Using stopTest:
  99 code::
 100 a = 5;
 101 w = SkipJack({ "watch...".postln; }, 0.5, { a == 10 }, "test");
 102 a = 10; // fulfil stopTest
 103 ::
 104
 105 Typical use: SkipJack updates a window displaying the state of some objects every now and then.
 106 code::
 107 (
 108 d = (a: 12, b: 24);
 109 d.win = Window("dict", Rect(0,0,200,60)).front;
 110 d.views = [\a, \b].collect { |name, i|
 111     StaticText(d.win, Rect(i * 100,0,96,20))
 112         .background_(Color.yellow).align_(0).string_(name);
 113 };
 114 w = SkipJack({
 115         "...".postln;
 116         [\a, \b].do { |name, i|
 117             d.views[i].string_(name ++ ":" + d[name])
 118         }
 119     },
 120     0.5,
 121     { d.win.isClosed },
 122     "showdict"
 123 );
 124 )
 125
 126 d.a = 123;      // updates should be displayed
 127 d.b = \otto;
 128 d.win.close;    // when window closes, SkipJack stops.
 129 ::
 130
 131 If you need to get rid of an unreachable skipjack:
 132 code::
 133 SkipJack({ "unreachable, unkillable...".postln }, name: "jack");
 134
 135 SkipJack.stopAll        // do this to stop all;
 136
 137 SkipJack.stop("jack");  // reach it by name and stop
 138 ::
 139