4.2. 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.
4.2.1. ClientServer
-
class
py4j.clientserver.
ClientServer
(java_parameters=None, python_parameters=None, python_server_entry_point=None)
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.
Parameters: |
- 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.
|
4.2.1.1. Examples
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.`
4.2.2. JavaParameters
-
class
py4j.clientserver.
JavaParameters
(address=‘127.0.0.1’, port=25333, auto_field=False, auto_close=True, auto_convert=False, eager_load=False, ssl_context=None, enable_memory_management=True, auto_gc=False, read_timeout=None)
Wrapper class that contains all parameters that can be passed to
configure a ClientServer.`
Parameters: |
- 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.
- read_timeout – if > 0, sets a timeout in seconds after
which the socket stops waiting for a response from the Java side.
|
4.2.3. PythonParameters
-
class
py4j.clientserver.
PythonParameters
(address=‘127.0.0.1’, port=25334, daemonize=False, daemonize_connections=False, eager_load=True, ssl_context=None, auto_gc=False, accept_timeout=’DEFAULT’, read_timeout=None)
Wrapper class that contains all parameters that can be passed to
configure a ClientServer
Parameters: |
- address – the address to which the client will request a
connection
- port – the port to which the client will request a connection.
Default is 25333.
- 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.
- 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.
|
4.2.4. JavaClient
-
class
py4j.clientserver.
JavaClient
(java_parameters, python_parameters, gateway_property=None)
Responsible for managing requests from Python to Java.
This implementation is thread-safe because it always use only one
ClientServerConnection per thread.
Parameters: |
- 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
|
-
get_thread_connection
()
Returns the ClientServerConnection associated with this thread. Can
be None.
-
set_thread_connection
(connection)
Associates a ClientServerConnection with the current thread.
Parameters: | connection – The ClientServerConnection to associate with the
current thread. |
4.2.5. PythonServer
-
class
py4j.clientserver.
PythonServer
(java_client, java_parameters, python_parameters, gateway_property)
Responsible for managing requests from Java to Python.
Parameters: |
- 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.
|
4.2.6. ClientServerConnection
-
class
py4j.clientserver.
ClientServerConnection
(java_parameters, python_parameters, gateway_property, java_client, python_server=None)
Default connection for a ClientServer instance
(socket-based, one per thread) responsible for communicating
with the Java Virtual Machine.
Parameters: |
- 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.
|
-
close
(reset=False)
-
connect_to_java_server
()
-
init_socket_from_python_server
(socket, stream)
-
run
()
-
send_command
(command)
-
shutdown_gateway
()
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.
-
start
()
-
wait_for_commands
()