Hide navigation sidebar
Hide table of contents sidebar
Skip to content
Back to top
Toggle table of contents sidebar

# `gevent.events` – Publish/subscribe event infrastructure

Publish/subscribe event infrastructure.

When certain “interesting” things happen during the lifetime of the process, gevent will “publish” an event (an object). That event is delivered to interested “subscribers” (functions that take one parameter, the event object).

Higher level frameworks may take this foundation and build richer models on it.

`zope.event` will be used to provide the functionality of `notify` and `subscribers`. See `zope.event.classhandler` for a simple class-based approach to subscribing to a filtered list of events, and see zope.component for a much higher-level, flexible system. If you are using one of these systems, you generally will not want to directly modify `subscribers`.

Added in version 1.3b1.

Changed in version 23.7.0: Now uses `importlib.metadata` instead of `pkg_resources` to locate entry points.

exception DoNotPatch

  Bases: `BaseException`

  Subscribers to will-patch events can raise instances of this class to tell gevent not to patch that particular item.

interface IEventLoopBlocked

  The event emitted when the event loop is blocked.

  This event is emitted in the monitor thread.

  Changed in version 24.11.1: Add the hub attribute.

  greenlet

    The greenlet that appeared to be blocking the loop.

  blocking_time

    The approximate time in seconds the loop has been blocked.

  info

    A list of string lines providing extra info. You may modify this list.

  hub

    If not None, the hub being blocked.

interface IGeventDidPatchAllEvent

  Extends: `gevent.events.IGeventDidPatchEvent`

  Event emitted after gevent has patched all modules, both builtin and those provided by plugins/subscribers.

  The values of the source and target attributes are undefined.

interface IGeventDidPatchBuiltinModulesEvent

  Extends: `gevent.events.IGeventDidPatchEvent`

  Event emitted after the builtin modules have been patched.

  If you’re going to monkey-patch a third-party library, this is usually the event to listen for.

  The values of the source and target attributes are undefined.

  patch_all_arguments

    A dictionary of all the arguments to `gevent.monkey.patch_all`. This dictionary should not be modified.

  patch_all_kwargs

    A dictionary of the extra arguments to `gevent.monkey.patch_all`. This dictionary should not be modified.

interface IGeventDidPatchEvent

  Extends: `gevent.events.IGeventPatchEvent`

  An event emitted after gevent has patched something.

interface IGeventDidPatchModuleEvent

  Extends: `gevent.events.IGeventDidPatchEvent`

  An event emitted after gevent has completed patching a specific module.

  module_name

    The name of the module being patched. This is the same as `target.__name__`.

interface IGeventPatchEvent

  The root for all monkey-patch events gevent emits.

  source

    The source object containing the patches.

  target

    The destination object to be patched.

interface IGeventWillPatchAllEvent

  Extends: `gevent.events.IGeventWillPatchEvent`

  An event emitted before gevent begins patching the system.

  Following this event will be a series of `IGeventWillPatchModuleEvent` and `IGeventDidPatchModuleEvent` for each patched module.

  Once the gevent builtin modules have been processed, `IGeventDidPatchBuiltinModulesEvent` will be emitted. Processing this event is an ideal time for third-party modules to be imported and patched (which may trigger its own will/did patch module events).

  Finally, a `IGeventDidPatchAllEvent` will be sent.

  If a subscriber to this event raises `DoNotPatch`, no patching will be done.

  The source and target attributes have undefined values.

  patch_all_arguments

    A dictionary of all the arguments to `gevent.monkey.patch_all`. This dictionary should not be modified.

  patch_all_kwargs

    A dictionary of the extra arguments to `gevent.monkey.patch_all`. This dictionary should not be modified.

  will_patch_module(module_name)

    Return whether the module named module_name will be patched.

interface IGeventWillPatchEvent

  Extends: `gevent.events.IGeventPatchEvent`

  An event emitted before gevent monkey-patches something.

  If a subscriber raises `DoNotPatch`, then patching this particular item will not take place.

interface IGeventWillPatchModuleEvent

  Extends: `gevent.events.IGeventWillPatchEvent`

  An event emitted before gevent begins patching a specific module.

  Both source and target attributes are module objects.

  module_name

    The name of the module being patched. This is the same as `target.__name__`.

  target_item_names

    The list of item names to patch. This can be modified in place with caution.

interface IMemoryUsageThresholdExceeded

  The event emitted when the memory usage threshold is exceeded.

  This event is emitted only while memory continues to grow above the threshold. Only if the condition or stabilized is corrected (memory usage drops) will the event be emitted in the future.

  This event is emitted in the monitor thread.

  mem_usage

    The current process memory usage, in bytes.

  max_allowed

    The maximum allowed memory usage, in bytes.

  memory_info

    The tuple of memory usage stats return by psutil.

interface IMemoryUsageUnderThreshold

  The event emitted when the memory usage drops below the threshold after having previously been above it.

  This event is emitted only the first time memory usage is detected to be below the threshold after having previously been above it. If memory usage climbs again, a `IMemoryUsageThresholdExceeded` event will be broadcast, and then this event could be broadcast again.

  This event is emitted in the monitor thread.

  mem_usage

    The current process memory usage, in bytes.

  max_allowed

    The maximum allowed memory usage, in bytes.

  max_memory_usage

    The memory usage that caused the previous IMemoryUsageThresholdExceeded event.

  memory_info

    The tuple of memory usage stats return by psutil.

interface IPeriodicMonitorThread

  The contract for the periodic monitoring thread that is started by the hub.

  add_monitoring_function(function, period)

    Schedule the function to be called approximately every period fractional seconds.

    The function receives one argument, the hub being monitored. It is called in the monitoring thread, not the hub thread. It must not attempt to use the gevent asynchronous API.

    If the function is already a monitoring function, then its period will be updated for future runs.

    If the period is `None`, then the function will be removed.

    A period less than or equal to zero is not allowed.

interface IPeriodicMonitorThreadStartedEvent

  The event emitted when a hub starts a periodic monitoring thread.

  You can use this event to add additional monitoring functions.

  monitor

    The instance of `IPeriodicMonitorThread` that was started.

class EventLoopBlocked(greenlet, blocking_time, info, *, hub=None)

  Bases: `object`

  The event emitted when the event loop is blocked.

  Implements `IEventLoopBlocked`.

class GeventDidPatchAllEvent(patch_all_arguments, patch_all_kwargs)

  Bases: `_PatchAllMixin`, `GeventDidPatchEvent`

  Implementation of `IGeventDidPatchAllEvent`.

  ENTRY_POINT_NAME = 'gevent.plugins.monkey.did_patch_all'

    The name of the setuptools entry point that is called when this event is emitted.

class GeventDidPatchBuiltinModulesEvent(patch_all_arguments, patch_all_kwargs)

  Bases: `_PatchAllMixin`, `GeventDidPatchEvent`

  Implementation of `IGeventDidPatchBuiltinModulesEvent`.

  ENTRY_POINT_NAME = 'gevent.plugins.monkey.did_patch_builtins'

    The name of the setuptools entry point that is called when this event is emitted.

class GeventDidPatchModuleEvent(module_name, source, target)

  Bases: `GeventDidPatchEvent`

  Implementation of `IGeventDidPatchModuleEvent`.

  ENTRY_POINT_NAME = 'gevent.plugins.monkey.did_patch_module'

    The name of the setuptools entry point that is called when this event is emitted.

class GeventPatchEvent(source, target)

  Bases: `object`

  Implementation of `IGeventPatchEvent`.

class GeventWillPatchAllEvent(patch_all_arguments, patch_all_kwargs)

  Bases: `_PatchAllMixin`, `GeventWillPatchEvent`

  Implementation of `IGeventWillPatchAllEvent`.

  ENTRY_POINT_NAME = 'gevent.plugins.monkey.will_patch_all'

    The name of the setuptools entry point that is called when this event is emitted.

class GeventWillPatchEvent(source, target)

  Bases: `GeventPatchEvent`

  Implementation of `IGeventWillPatchEvent`.

class GeventWillPatchModuleEvent(module_name, source, target, items)

  Bases: `GeventWillPatchEvent`

  Implementation of `IGeventWillPatchModuleEvent`.

  ENTRY_POINT_NAME = 'gevent.plugins.monkey.will_patch_module'

    The name of the setuptools entry point that is called when this event is emitted.

class MemoryUsageThresholdExceeded(mem_usage, max_allowed, memory_info)

  Bases: `_AbstractMemoryEvent`

  Implementation of `IMemoryUsageThresholdExceeded`.

class MemoryUsageUnderThreshold(mem_usage, max_allowed, memory_info, max_usage)

  Bases: `_AbstractMemoryEvent`

  Implementation of `IMemoryUsageUnderThreshold`.

class PeriodicMonitorThreadStartedEvent(monitor)

  Bases: `object`

  The implementation of `IPeriodicMonitorThreadStartedEvent`.

  Changed in version 24.11.1: Now actually implements the promised interface.

  ENTRY_POINT_NAME = 'gevent.plugins.hub.periodic_monitor_thread_started'

    The name of the setuptools entry point that is called when this event is emitted.

subscribers = []

  Applications may register for notification of events by appending a callable to the `subscribers` list.

  Each subscriber takes a single argument, which is the event object being published.

  Exceptions raised by subscribers will be propagated without running any remaining subscribers.

  This is an alias for `zope.event.subscribers`; prefer to use that attribute directly.