Class NettyPythonEventLoop

java.lang.Object
io.micronaut.context.python.netty.NettyPythonEventLoop
All Implemented Interfaces:
PythonEventLoop
@Internal public final class NettyPythonEventLoop extends Object implements PythonEventLoop
Python event loop backed by a Netty EventLoop.

This class is intentionally a narrow bridge between Python's asyncio transport protocol APIs and Micronaut's Netty event loop. It does not try to expose raw Netty channels to Python callers. The public nested transport/server/facade types are GraalPy host objects whose method names are part of the Python-facing surface, including snake_case names that mirror asyncio. Do not rename those methods to satisfy Java style checks unless the Python shims and tests are updated at the same time.

All callbacks into Python protocols are made from the Netty event loop thread. When this loop is entered from a different Java thread, work is rescheduled onto Netty before touching channel state or invoking Python callbacks.

  • Constructor Details

    • NettyPythonEventLoop

      public NettyPythonEventLoop(io.netty.channel.EventLoop eventLoop)
      Parameters:
      eventLoop - The Netty event loop.

  • Method Details

    • inEventLoop

      public boolean inEventLoop()
      Description copied from interface: PythonEventLoop
      Used to decide whether Python work can run immediately or must be queued.
      Specified by:
      inEventLoop in interface PythonEventLoop
      Returns:
      Whether the current thread is this event-loop thread.

    • execute

      public void execute(Runnable runnable)
      Description copied from interface: PythonEventLoop
      Queue a callback for serialized execution on the loop.
      Specified by:
      execute in interface PythonEventLoop
      Parameters:
      runnable - The callback.

    • schedule

      public ScheduledFuture<?> schedule(Runnable runnable, long delay, TimeUnit unit)
      Description copied from interface: PythonEventLoop
      Queue a callback after the requested delay using loop time.
      Specified by:
      schedule in interface PythonEventLoop
      Parameters:
      runnable - The callback.
      delay - The delay.
      unit - The delay unit.
      Returns:
      The scheduled future.

    • executeCallback

      public void executeCallback(org.graalvm.polyglot.Value callback)
      Description copied from interface: PythonEventLoop
      Queue a Python callback for execution on the loop.

      A loop that owns a GraalPy context runs the callback inside an execution frame of the callback's context, so shutdown waits for callbacks scheduled with call_soon. The PropagatedContext of the callback is not captured here: it belongs to the asyncio task that owns the callback, which keeps it in its contextvars and restores it when the callback runs, so a task resumed by another task (a shared asyncio.Event) or by a Java thread completing an awaited stage keeps its own context.

      Specified by:
      executeCallback in interface PythonEventLoop
      Parameters:
      callback - The Python callable.

    • scheduleCallback

      public ScheduledFuture<?> scheduleCallback(org.graalvm.polyglot.Value callback, long delay, TimeUnit unit)
      Description copied from interface: PythonEventLoop
      Queue a Python callback after the requested delay using loop time.
      Specified by:
      scheduleCallback in interface PythonEventLoop
      Parameters:
      callback - The Python callable.
      delay - The delay.
      unit - The delay unit.
      Returns:
      The scheduled future.

    • time

      public double time()
      Description copied from interface: PythonEventLoop
      Returns the monotonic time base exposed to Python's asyncio APIs.
      Specified by:
      time in interface PythonEventLoop
      Returns:
      Event-loop time in seconds.

    • equals

      public boolean equals(Object object)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • eventLoop

      public io.netty.channel.EventLoop eventLoop()
      Returns the underlying Netty event loop.
      Returns:
      The underlying Netty event loop.

    • createConnection

      public CompletionStage<Object[]> createConnection(org.graalvm.polyglot.Value protocolFactory, String host, int port, @Nullable String localHost, int localPort, @Nullable Object ssl, @Nullable String serverHostname, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout)
      Create a Netty-backed asyncio TCP connection.
      Parameters:
      protocolFactory - The Python protocol factory.
      host - The remote host.
      port - The remote port.
      localHost - The local host, or null.
      localPort - The local port, or -1.
      ssl - TLS options.
      serverHostname - The TLS server hostname.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      Returns:
      A stage completing with transport and protocol.

    • createConnection

      public CompletionStage<Object[]> createConnection(org.graalvm.polyglot.Value protocolFactory, String host, int port, @Nullable String localHost, int localPort, @Nullable Object ssl, @Nullable String serverHostname, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout, String family)
      Connect a TCP client, resolving the host to an address of the requested family.
      Parameters:
      protocolFactory - The asyncio protocol factory.
      host - The remote host.
      port - The remote port.
      localHost - The local host to bind, or null.
      localPort - The local port to bind, or -1.
      ssl - TLS options, or null.
      serverHostname - The TLS server name, or null.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      family - inet, inet6 or empty for any address family
      Returns:
      A stage completing with transport and protocol.

    • createServer

      public CompletionStage<NettyPythonEventLoop.NettyServer> createServer(org.graalvm.polyglot.Value protocolFactory, @Nullable String host, int port, int backlog, boolean reuseAddress, boolean reusePort, boolean startServing, @Nullable Object ssl, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout)
      Create a Netty-backed asyncio TCP server.
      Parameters:
      protocolFactory - The Python protocol factory.
      host - The local host.
      port - The local port.
      backlog - The listen backlog.
      reuseAddress - Whether address reuse is enabled.
      reusePort - Whether port reuse is requested.
      startServing - Whether to start accepting connections immediately.
      ssl - TLS options.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      Returns:
      A stage completing with the server.

    • createServer

      public CompletionStage<NettyPythonEventLoop.NettyServer> createServer(org.graalvm.polyglot.Value protocolFactory, @Nullable String host, int port, int backlog, boolean reuseAddress, boolean reusePort, boolean startServing, @Nullable Object ssl, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout, String family)
      Bind a TCP server on an address of the requested family.
      Parameters:
      protocolFactory - The asyncio protocol factory.
      host - The host to bind, or null for every address.
      port - The port to bind.
      backlog - The accept backlog.
      reuseAddress - Whether to set SO_REUSEADDR.
      reusePort - Whether to set SO_REUSEPORT.
      startServing - Whether to accept connections right away.
      ssl - TLS options, or null.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      family - inet, inet6 or empty for any address family
      Returns:
      A stage completing with the server.

    • connectAcceptedSocket

      public CompletionStage<Object[]> connectAcceptedSocket(org.graalvm.polyglot.Value protocolFactory, Object socket, @Nullable Object ssl, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout)
      Wrap a Netty channel accepted elsewhere as an asyncio TCP transport.
      Parameters:
      protocolFactory - The Python protocol factory.
      socket - The accepted Netty channel or transport exposing one.
      ssl - TLS options.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      Returns:
      A stage completing with transport and protocol.

    • createUnixConnection

      public CompletionStage<Object[]> createUnixConnection(org.graalvm.polyglot.Value protocolFactory, String path, @Nullable Object ssl, @Nullable String serverHostname, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout)
      Create a Netty-backed asyncio Unix-domain socket connection.
      Parameters:
      protocolFactory - The Python protocol factory.
      path - The Unix-domain socket path.
      ssl - TLS options.
      serverHostname - The TLS server hostname.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      Returns:
      A stage completing with transport and protocol.

    • createUnixServer

      public CompletionStage<NettyPythonEventLoop.NettyServer> createUnixServer(org.graalvm.polyglot.Value protocolFactory, String path, int backlog, boolean startServing, @Nullable Object ssl, @Nullable Double sslHandshakeTimeout, @Nullable Double sslShutdownTimeout)
      Create a Netty-backed asyncio Unix-domain socket server.
      Parameters:
      protocolFactory - The Python protocol factory.
      path - The Unix-domain socket path.
      backlog - The listen backlog.
      startServing - Whether to start accepting connections immediately.
      ssl - TLS options.
      sslHandshakeTimeout - The TLS handshake timeout in seconds.
      sslShutdownTimeout - The TLS shutdown timeout in seconds.
      Returns:
      A stage completing with the server.

    • createDatagramEndpoint

      public CompletionStage<Object[]> createDatagramEndpoint(org.graalvm.polyglot.Value protocolFactory, @Nullable String localHost, int localPort, @Nullable String remoteHost, int remotePort, boolean allowBroadcast, boolean reusePort)
      Create a Netty-backed asyncio datagram endpoint.
      Parameters:
      protocolFactory - The Python protocol factory.
      localHost - The local host, or null.
      localPort - The local port, or -1.
      remoteHost - The remote host, or null.
      remotePort - The remote port, or -1.
      allowBroadcast - Whether broadcast is enabled.
      reusePort - Whether port reuse is requested.
      Returns:
      A stage completing with transport and protocol.

    • createDatagramEndpoint

      public CompletionStage<Object[]> createDatagramEndpoint(org.graalvm.polyglot.Value protocolFactory, @Nullable String localHost, int localPort, @Nullable String remoteHost, int remotePort, boolean allowBroadcast, boolean reusePort, String family)
      Open a datagram endpoint on an address of the requested family.
      Parameters:
      protocolFactory - The asyncio datagram protocol factory.
      localHost - The local host, or null.
      localPort - The local port, or -1.
      remoteHost - The remote host to connect to, or null.
      remotePort - The remote port, or -1.
      allowBroadcast - Whether to set SO_BROADCAST.
      reusePort - Whether to set SO_REUSEPORT.
      family - inet, inet6 or empty for any address family
      Returns:
      A stage completing with transport and protocol.