Mercurial > pylearn

annotate doc/v2_planning/plugin.txt @ 1189:0e12ea6ba661

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
fix many rst syntax error warning.
author Frederic Bastien <nouiz@nouiz.org>
date Fri, 17 Sep 2010 20:55:18 -0400
parents a1957faecc9b
children
rev   line source
1118
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
1
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
2 ======================================
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
3 Plugin system for iterative algorithms
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
4 ======================================
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
5
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
6 I would like to propose a plugin system for iterative algorithms in
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
7 Pylearn. Basically, it would be useful to be able to sandwich
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
8 arbitrary behavior in-between two training iterations of an algorithm
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
9 (whenever applicable). I believe many mechanisms are best implemented
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
10 this way: early stopping, saving checkpoints, tracking statistics,
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
11 real time visualization, remote control of the process, or even
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
12 interlacing the training of several models and making them interact
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
13 with each other.
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
14
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
15 So here is the proposal: essentially, a plugin would be a (schedule,
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
16 timeline, function) tuple.
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
17
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
18 Schedule
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
19 ========
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
20
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
21 The schedule is some function that takes two "times", t1 and t2, and
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
22 returns True if the plugin should be run in-between these times. The
1119
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
23 indices refer to a "timeline" unit described below (e.g. "real time" or
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
24 "iterations"). The reason why we check a time range [t1, t2] rather than
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
25 some discrete time t is that we do not necessarily want to schedule plugins
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
26 on iteration numbers. For instance, we could want to run a plugin every
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
27 second, or every minute, and then [t1, t2] would be the start time and end
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
28 time of the last iteration - and then we run the plugin whenever a new
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
29 second started in that range (but still on training iteration
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
30 boundaries). Alternatively, we could want to run a plugin every n examples
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
31 seen - but if we use mini-batches, the nth example might be square in the
81ea57c6716d clarification to plugin.txt
Yoshua Bengio <bengioy@iro.umontreal.ca>
parents: 1118
diff changeset
32 middle of a batch.
1118
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
33
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
34 I've implemented a somewhat elaborate schedule system. `each(10)`
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
35 produces a schedule that returns true whenever a multiple of 10 is in
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
36 the time range. `at(17, 153)` produces one that returns true when 17
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
37 or 143 is in the time range. Schedules can be combined and negated,
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
38 e.g. `each(10) & ~at(20, 30)` (execute at each 10, except at 20 and
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
39 30). So that gives a lot of flexibility as to when you want to do
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
40 things.
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
41
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
42 Timeline
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
43 ========
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
44
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
45 This would be a string indicating on what "timeline" the schedule is
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
46 supposed to operate. For instance, there could be a "real time"
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
47 timeline, an "algorithm time" timeline, an "iterations" timeline, a
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
48 "number of examples" timeline, and so on. This means you can schedule
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
49 some action to be executed every actual second, or every second of
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
50 training time (ignoring time spent executing plugins), or every
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
51 discrete iteration, or every n examples processed. This might be a
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
52 bloat feature (it was an afterthought to my original design, anyway),
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
53 but I think that there are circumstances where each of these options
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
54 is the best one.
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
55
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
56 Function
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
57 ========
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
58
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
59 The plugin function would receive some object containing the time
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
60 range, a flag indicating whether the training has started, a flag
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
61 indicating whether the training is done (which they can set in order
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
62 to stop training), as well as anything pertinent about the model.
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
63
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
64 Implementation
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
65 ==============
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
66
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
67 I have implemented the feature in plugin.py, in this directory. Simply
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
68 run python plugin.py to test it.
8cc324f388ba proposal for a plugin system
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents:
diff changeset
69
1135
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
70
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
71
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
72 ===============
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
73 Revised version
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
74 ===============
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
75
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
76 Taking into account ideas thrown around during the September 16
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
77 meeting I (OB) have made the following modifications to my original
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
78 proposal:
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
79
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
80 Event objects
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
81 =============
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
82
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
83 In the revised framework, an Event is a generic object which can
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
84 contain any attributes you want, with one privileged attribute, the
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
85 'type' attribute, which is a string. I expect the following attributes
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
86 to be used widely:
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
87
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
88 * type: this is a string describing the abstract semantics of this
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
89 event ("tick", "second", "millisecond", "batch", etc.)
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
90
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
91 * issuer: a pointer to the plugin that issued this event. This allows
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
92 for fine grained filtering in the case where several plugins can
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
93 fire the same event type
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
94
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
95 * time: an integer or float index on an abstract timeline. For
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
96 instance, the "tick" event would have a "time" field, which would be
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
97 increased by one every time the event is fired. Pretty much all
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
98 recurrent events should include this.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
99
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
100 * data: some data associated to the event. presumably it doesn't have
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
101 to be named "data", and more than one data field could be given.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
102
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
103 The basic idea is that it should be possible to say: "I want this
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
104 plugin to be executed every tenth time an event of this type is fired
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
105 by this plugin", or any subset of these conditions.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
106
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
107 Matching events
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
108 ===============
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
109
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
110 When registering a plugin, you specify a sort of "abstract event" that
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
111 an event must "match" in order to be fed to the plugin. This can be
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
112 done by simply instantiating an event with the fields you want to
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
113 match. I think examples would explain best my idea
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
114 (sch.schedule_plugin = add a plugin to the scheduler):
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
115
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
116 # Print the error on every parameter update (learner given in the event)
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
117 sch.schedule_plugin(Event("parameter_update"), PrintError())
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
118 # Print the reconstruction error of daa0 whenever it does a parameter update
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
119 sch.schedule_plugin(Event("parameter_update", issuer = daa0), PrintReconstructionError())
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
120 # Save the learner every 10 minutes
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
121 sch.schedule_plugin(Event("minute", time = each(10)), Save(learner))
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
122
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
123 The events given as first argument to schedule_plugin are not real
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
124 events: they are "template events" meant to be *matched* against the
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
125 real events that will be fired. If the terminology is confusing, it
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
126 would not be a problem to use another class with a better name (for
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
127 example, On("minute", time = each(10)) could be clearer than
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
128 Event(...), I don't know).
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
129
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
130 Note that fields in these Event objects can be a special kind of
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
131 object, a Matcher, which allows to filter events based on arbitrary
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
132 conditions. My Schedule objects (each, at, etc.) now inherit from
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
133 Matcher. You could easily have a matcher that allows you to match
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
134 issuers that are instances of a certain class, or matches every single
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
135 event (I have an example of the latter in plugin.py).
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
136
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
137 Plugins
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
138 =======
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
139
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
140 The plugin class would have the following methods:
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
141
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
142 * attach(scheduler): tell the plugin that it is being scheduled by the
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
143 scheduler, store the scheduler in self. The method can return self,
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
144 or a copy of itself.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
145
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
146 * fire(type, **attributes): adds Event(type, issuer = self, **attributes)
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
147 to the event queue of self.scheduler
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
148
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
149 Scheduler
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
150 =========
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
151
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
152 A Scheduler would have a schedule_plugin(event_template, plugin)
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
153 method to add plugins, a queue(event) method to queue a new event, and
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
154 it would be callable.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
155
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
156 My current version proceeds as follows:
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
157
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
158 * Fire Event("begin"). Somewhat equivalent to "tick" at time 0, but I
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
159 find it cleaner to have a special event to mark the beginning of the
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
160 event loop.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
161 * Infinite loop
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
162 * Fire Event("tick", time = <iteration#>)
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
163 * Loop until the queue is empty
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
164 * Pop event, execute all plugins that respond to it
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
165 * Check if event.type == "terminate". If so, stop.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
166
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
167 Varia
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
168 =====
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
169
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
170 I've made a very simple implementation of a DispatchPlugin which, upon
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
171 reception of an event, dispatches it to its "on_<event.type>" method
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
172 (or calls a fallback). It seems nice. However, in order for it to work
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
173 reliably, it has to be registered on all events, and I'm not sure it
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
174 can scale well to more complex problems where the source of events is
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
175 important.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
176
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
177 Implementation
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
178 ==============
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
179
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
180 See plugin.py.
a1957faecc9b revised plugin interface and implementation
Olivier Breuleux <breuleuo@iro.umontreal.ca>
parents: 1119
diff changeset
181