twisted.internet.interfaces.IReactorCore

interface documentation

class IReactorCore(Interface): (source)

Known subclasses: twisted.trial._dist.disttrial.IDistTrialReactor

Known implementations: twisted.internet.base.ReactorBase, twisted.internet.testing.MemoryReactor

Core methods that a Reactor must implement.

Method	`addSystemEventTrigger`	Add a function to be called when a system event occurs.
Method	`callWhenRunning`	Call a function when the reactor is running.
Method	`crash`	Stop the main loop immediately, without firing any system events.
Method	`fireSystemEvent`	Fire a system-wide event.
Method	`iterate`	Run the main loop's I/O polling function for a period of time.
Method	`removeSystemEventTrigger`	Removes a trigger added with addSystemEventTrigger.
Method	`resolve`	Asynchronously resolve a hostname to a single IPv4 address.
Method	`run`	Fire 'startup' System Events, move the reactor to the 'running' state, then run the main loop until it is stopped with `stop()` or `crash()`.
Method	`stop`	Fire 'shutdown' System Events, which will move the reactor to the 'stopped' state and cause `reactor.run()` to exit.
Attribute	`running`	A `bool` which is `True` from during startup to during shutdown and `False` the rest of the time.

def addSystemEventTrigger(phase: str, eventType: str, callable: Callable[..., Any], *args: object, **kwargs: object) -> Any: (source) ¶

Add a function to be called when a system event occurs.

Each "system event" in Twisted, such as 'startup', 'shutdown', and 'persist', has 3 phases: 'before', 'during', and 'after' (in that order, of course). These events will be fired internally by the Reactor.

An implementor of this interface must only implement those events described here.

Callbacks registered for the "before" phase may return either None or a Deferred. The "during" phase will not execute until all of the Deferreds from the "before" phase have fired.

Once the "during" phase is running, all of the remaining triggers must execute; their return values must be ignored.

Parameters
phase:`str`	a time to call the event -- either the string 'before', 'after', or 'during', describing when to call it relative to the event's execution.
eventType:`str`	this is a string describing the type of event.
callable:`Callable[..., Any]`	the object to call before shutdown.
*args:`object`	the arguments to call it with.
**kwargs:`object`	the keyword arguments to call it with.
Returns
`Any`	an ID that can be used to remove this call with removeSystemEventTrigger.

def callWhenRunning(callable: Callable[..., Any], *args: object, **kwargs: object) -> Optional[Any]: (source) ¶

Call a function when the reactor is running.

If the reactor has not started, the callable will be scheduled to run when it does start. Otherwise, the callable will be invoked immediately.

Parameters
callable:`Callable[..., Any]`	the callable object to call later.
*args:`object`	the arguments to call it with.
**kwargs:`object`	the keyword arguments to call it with.
Returns
`Optional[Any]`	None if the callable was invoked, otherwise a system event id for the scheduled call.

def crash(): (source) ¶

Stop the main loop *immediately*, without firing any system events.

This is named as it is because this is an extremely "rude" thing to do; it is possible to lose data and put your system in an inconsistent state by calling this. However, it is necessary, as sometimes a system can become wedged in a pre-shutdown call.

def fireSystemEvent(eventType: str): (source) ¶

Fire a system-wide event.

System-wide events are things like 'startup', 'shutdown', and 'persist'.

def iterate(delay: float): (source) ¶

Run the main loop's I/O polling function for a period of time.

This is most useful in applications where the UI is being drawn "as fast as possible", such as games. All pending IDelayedCalls will be called.

The reactor must have been started (via the run() method) prior to any invocations of this method. It must also be stopped manually after the last call to this method (via the stop() method). This method is not re-entrant: you must not call it recursively; in particular, you must not call it while the reactor is running.

def removeSystemEventTrigger(triggerID: Any): (source) ¶

Removes a trigger added with addSystemEventTrigger.

Parameters
triggerID:`Any`	a value returned from addSystemEventTrigger.
Raises
`KeyError`	If there is no system event trigger for the given `triggerID`.
`ValueError`	If there is no system event trigger for the given `triggerID`.
`TypeError`	If there is no system event trigger for the given `triggerID`.

def resolve(name: str, timeout: Sequence[int] = (1, 3, 11, 45)) -> Deferred[str]: (source) ¶

Asynchronously resolve a hostname to a single IPv4 address.

Parameters
name:`str`	The hostname to resolve.
timeout:`Sequence[int]`	A sequence of timeouts, meant to mirror the sequence of timeouts used for each hop in recursive queries. Note that different implementations of the resolver backend may not honor this timeout as such, or at all; if the underlying platform API supports it, implementations make a best-effort attempt to cancel the underlying resolution if the sum of these timeouts elapses.
Returns
`Deferred[str]`	Undocumented
Note
Rather than calling this API directly, you probably want to use `twisted.internet.endpoints.HostnameEndpoint` to connect to a hostname. If you do want to resolve a hostname without connecting to it, see `IReactorPluggableNameResolver` and `IHostnameResolver` so that you can receive multiple results and IPv6 addresses.

def run(): (source) ¶

Fire 'startup' System Events, move the reactor to the 'running' state, then run the main loop until it is stopped with stop() or crash().

def stop(): (source) ¶

Fire 'shutdown' System Events, which will move the reactor to the 'stopped' state and cause reactor.run() to exit.

running = (source) ¶

A bool which is True from during startup to during shutdown and False the rest of the time.