py4j.clientserver — Py4J Single Threading Model Implementation¶The py4j.clientserver module defines an implementation of Python Server
and Java client that ensures that commands started from a Python or Java thread
are always executed on the same Java or Python thread.
For example, if a command to Python is sent from Java UI thread and the Python code calls some Java code, the Java code will be executed in the UI thread.
Py4J users are expected to only use explicitly ClientServer and optionally, JavaParameters and PythonParameters. The other module members are documented
to support the extension of Py4J.
Subclass of JavaGateway that implements a different threading model: a thread always use the same connection to the other side so callbacks are executed in the calling thread.
For example, if Python thread 1 calls Java, and Java calls Python, the callback (from Java to Python) will be executed in Python thread 1.
Note about authentication: to enable authentication
java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
python_server_entry_point – can be requested by the Java side if Java is driving the communication.
Using the jvm property:
>>> clientserver = ClientServer()
>>> l = clientserver.jvm.java.util.ArrayList()
>>> l.append(10)
>>> l.append(1)
>>> jvm.java.util.Collections.sort(l)
>>> l
[1, 10]
The ClientServer class is a subclass
of JavaGateway is fully compatible
with all examples and code written for a JavaGateway.`
Wrapper class that contains all parameters that can be passed to configure a ClientServer.`
address – the address to which the client will request a connection. If you’re assing a SSLContext with check_hostname=True then this address must match (one of) the hostname(s) in the certificate the gateway server presents.
port – the port to which the client will request a connection. Default is 25333.
auto_field – if False, each object accessed through this gateway won”t try to lookup fields (they will be accessible only by calling get_field). If True, fields will be automatically looked up, possibly hiding methods of the same name and making method calls less efficient.
auto_close – if True, the connections created by the client close the socket when they are garbage collected.
auto_convert – if True, try to automatically convert Python objects like sequences and maps to Java Objects. Default value is False to improve performance and because it is still possible to explicitly perform this conversion.
eager_load – if True, the gateway tries to connect to the JVM by calling System.currentTimeMillis. If the gateway cannot connect to the JVM, it shuts down itself and raises an exception.
ssl_context – if not None, SSL connections will be made using this SSLContext
enable_memory_management – if True, tells the Java side when a JavaObject (reference to an object on the Java side) is garbage collected on the Python side.
auto_gc – if True, call gc.collect() before sending a command to the Java side. This should prevent the gc from running between sending the command and waiting for an anwser. False by default because this case is extremely unlikely. Legacy option no longer used.
read_timeout – if > 0, sets a timeout in seconds after which the socket stops waiting for a response from the Java side.
daemonize_memory_management – if True, the worker Thread making the garbage collection requests will be daemonized. This means that the Python side might not send all garbage collection requests if it exits. If False, memory management will block the Python program exit until all requests are sent.
auth_token – if provided, an authentication that token clients must provide to the server when connecting.
Wrapper class that contains all parameters that can be passed to configure a ClientServer
address – the address to which the client will request a connection
port – the port to which the client will request a connection. Default is 25334.
daemonize – If True, will set the daemon property of the server thread to True. The callback server will exit automatically if all the other threads exit.
daemonize_connections – If True, callback server connections are executed in daemonized threads and will not block the exit of a program if non daemonized threads are finished.
eager_load – If True, the callback server is automatically started when the JavaGateway is created.
ssl_context – if not None, the SSLContext’s certificate will be presented to callback connections.
auto_gc – if True, call gc.collect() before returning a response to the Java side. This should prevent the gc from running between sending the response and waiting for a new command. False by default because this case is extremely unlikely but could break communication. Legacy option no longer used.
accept_timeout – if > 0, sets a timeout in seconds after which the callbackserver stops waiting for a connection, sees if the callback server should shut down, and if not, wait again for a connection. The default is 5 seconds: this roughly means that if can take up to 5 seconds to shut down the callback server.
read_timeout – if > 0, sets a timeout in seconds after which the socket stops waiting for a call or command from the Java side.
propagate_java_exceptions – if True, any Py4JJavaError raised by a Python callback will cause the nested java_exception to be thrown on the Java side. If False, the Py4JJavaError will manifest as a Py4JException on the Java side, just as with any other kind of Python exception. Setting this option is useful if you need to implement a Java interface where the user of the interface has special handling for specific Java exception types.
auth_token – if provided, an authentication token that clients must provide to the server when connecting.
Responsible for managing requests from Python to Java.
This implementation is thread-safe because it always use only one ClientServerConnection per thread.
java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
gateway_property – used to keep gateway preferences without a cycle with the JavaGateway
finalizer_deque – deque used to manage garbage collection requests.
Tells the Java side that there is no longer a reference to this JavaObject on the Python side. If enqueue is True, sends the request to the FinalizerWorker deque. Otherwise, sends the request to the Java side.
Returns the ClientServerConnection associated with this thread. Can be None.
Associates a ClientServerConnection with the current thread.
connection – The ClientServerConnection to associate with the current thread.
Sends a shutdown command to the gateway. This will close the gateway server: all active connections will be closed. This may be useful if the lifecycle of the Java program must be tied to the Python program.
Responsible for managing requests from Java to Python.
java_client – the gateway client used to call Java objects.
java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
gateway_property – used to keep gateway preferences.
Default connection for a ClientServer instance (socket-based, one per thread) responsible for communicating with the Java Virtual Machine.
java_parameters – collection of parameters and flags used to configure the JavaGateway (Java client)
python_parameters – collection of parameters and flags used to configure the CallbackServer (Python server)
gateway_property – used to keep gateway preferences.
java_client – the gateway client used to call Java objects.
python_server – the Python server used to receive commands from Java. Only provided if created from Python server.
Sends a shutdown command to the Java side.
This will close the ClientServer on the Java side: all active connections will be closed. This may be useful if the lifecycle of the Java program must be tied to the Python program.