mirrors/xonsh
1
0
Fork 0
mirror of https://github.com/xonsh/xonsh.git synced 2025-03-04 08:24:40 +01:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Expand on events under the hood some.

Browse source
This commit is contained in:
Jamie Bliss 2016-08-27 23:27:52 -04:00
parent e446c63e60
commit 74c423f215
1 changed files with 21 additions and 12 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

33
docs/advanced_events.rst
View file

@ -9,6 +9,23 @@ details of the event system.
You may also find the `events API reference <api/events.html>`_ useful.
Why Unordered?
==============
Yes, handler call order is not guarenteed. Please don't file bugs about this.
This was chosen because the order of handler registration is dependant on load order, which is
stable in a release but not something generally reasoned about. In addition, xontribs mean that we
don't know what handlers could be registered. So even an "ordered" event system would be unable to
make guarentees about ordering because of the larger system.
Because of this, the event system is not ordered; this is a form of abstraction. Order-dependant
semantics are not encouraged by the built-in methods.
So how do I handle results?
===========================
``Event.fire()`` returns a list of the returns from the handlers. You should merge this list in an
appropriate way.
What are Species?
=================
In xonsh, events come in species. Each one may look like an event and quack like an event, but they
@ -17,17 +34,9 @@ behave differently.
This was done because load hooks look like events and quack like events, but they have different
semantics. See `LoadEvents <api/events.html#xonsh.events.LoadEvent>`_ for details.
Why Unordered?
==============
Yes, handler call order is not guarenteed. Please don't file bugs about this.
In order to turn an event from the default ``Event``, you must transmogrify it, using
``events.transmogrify()``. The class the event is turned in to must be a subclass of ``AbstractEvent``.
This was chosen because the order of handler registration is dependant on load order, which is
stable in a release but not something generally reasoned about. In addition, xontribs mean that we
don't know what handlers could be registered.
(Under the hood, transmogrify creates a new instance and copies the handlers and docstring from the
old instance to the new one.)
Because of this, the event system is not ordered, and order-dependant semantics are not encouraged.
So how do I handle results?
===========================
``Event.fire()`` returns a list of the returns from the handlers. You should merge this list in an
appropriate way.