# Event system

Module yoton.events

Yoton comes with a simple event system to enable event-driven applications.

All channels are capable of running without the event system, but some channels have limitations. See the documentation of the channels for more information. Note that signals only work if events are processed.

class `yoton.``Signal`

  Inherits from object

  The purpose of a signal is to provide an interface to bind/unbind to events and to fire them.

  One can bind() or unbind() a callable to the signal. When emitted, an event is created for each bound handler. Therefore, the event loop must run for signals to work.

  Some signals call the handlers using additional arguments to specify specific information.

  PROPERTIES

  `type`

    The type (__class__) of this event.

  METHODS

  `bind`(func)

    Add an eventhandler to this event.

    The callback/handler (func) must be a callable. It is called with one argument: the event instance, which can contain additional information about the event.

  `emit`(*args, **kwargs)

    Emit the signal, calling all bound callbacks with *args and **kwargs. An event is queues for each callback registered to this signal. Therefore it is safe to call this method from another thread.

  `emit_now`(*args, **kwargs)

    Emit the signal now. All handlers are called from the calling thread. Beware, this should only be done from the same thread that runs the event loop.

  `unbind`(func=None)

    Unsubscribe a handler, If func is None, remove all handlers.

class `yoton.``Timer`(interval=1.0, oneshot=True)

  Inherits from Signal

  Timer class. You can bind callbacks to the timer. The timer is fired when it runs out of time.

  Parameters

  interval : number
    The interval of the timer in seconds.
  oneshot : bool
    Whether the timer should do a single shot, or run continuously.

  PROPERTIES

  `interval`

    Set/get the timer’s interval in seconds.

  `oneshot`

    Set/get whether this is a oneshot timer. If not is runs continuously.

  `running`

    Get whether the timer is running.

  METHODS

  `start`(interval=None, oneshot=None)

    Start the timer. If interval or oneshot are not given, their current values are used.

  `stop`()

    Stop the timer from running.

`yoton.``call_later`(func, timeout=0.0, *args, **kwargs)

  Call the given function after the specified timeout.

  Parameters

  func : callable
    The function to call.
  timeout : number
    The time to wait in seconds. If zero, the event is put on the event queue. If negative, the event will be put at the front of the event queue, so that it’s processed asap.
  args : arguments
    The arguments to call func with.
  kwargs: keyword arguments.
    The keyword arguments to call func with.

`yoton.``process_events`(block=False)

  Process all yoton events currently in the queue. This function should be called periodically in order to keep the yoton event system running.

  block can be False (no blocking), True (block), or a float blocking for maximally ‘block’ seconds.

`yoton.``start_event_loop`()

  Enter an event loop that keeps calling yoton.process_events(). The event loop can be stopped using stop_event_loop().

`yoton.``stop_event_loop`()

  Stops the event loop if it is running.

`yoton.``embed_event_loop`(callback)

  Embed the yoton event loop in another event loop. The given callback is called whenever a new yoton event is created. The callback should create an event in the other event-loop, which should lead to a call to the process_events() method. The given callback should be thread safe.

  Use None as an argument to disable the embedding.