Fundamentally, PGX is designed for server-client execution. It assumes the following situations:
The design of the PGX API reflects consideration of these situations.
In PGX, each client maintains its own session, an isolated, private workspace. Therefore, clients first have
to obtain a PgxSession
object from a PGX ServerInstance
before they can perform any analysis.
The PGX API is designed for asynchronous execution. That means that each computationally intensive method in
the PGX API immediately returns a PgxFuture
object without waiting for the request to finish. The PgxFuture
class implements the
Future interface,
which can be used to retrieve the result of a computation at some point in the future.
Note: The Asynchronous Execution aspect of this design facilitates multiple (remote) clients submitting requests to a
single server. A request from one client may be queued up to wait until PGX resources become available. The
asynchronous API allows the client (or calling thread) to work on other tasks until PGX completes the request. Read more
about what you can do with PgxFuture
in this chapter.
No object returned by the PGX API returns a direct reference of PGX internal objects (e.g., the graph or its properties) to the client.
Instead, the PGX API only returns lightweight, stateless pointer objects to those objects, which hold nothing more than the ID (name) of the server-side object to which they are pointing.
Being an in-memory analytic engine, the PGX server might allocate large amounts of memory to hold the graph data of clients. Therefore, it is important that client sessions clean up their resources once they have ended. The PGX API supports several features to make this easier:
Every object returned by the PGX API pointing to a server-side resource implements the Destroyable
interface,
which means all memory-consuming client-side objects can be destroyed the same way. For example:
PgxGraph myGraph = ... myGraph.destroyAsync(); // request destruction of myGraph, don't wait for response try { myGraph.destroy(); // blocks caller thread until destruction was done } catch (ExecutionException e) { // destruction failed }
Destroyable
extends AutoClosable,
so users can leverage Java's built-in resource management syntax:
try (PgxGraph myGraph = session.readGraphWithProperties(config)) { // do something with myGraph } // myGraph is destroyed
Some Destroyable
classes implement
Object#finalize(), implying
that Java's Finalizer thread calls destroy()
automatically after the JVM garbage collects the client
object. There are some exceptions to this behavior, however. For example, graph properties can be retrieved by name,
so they are not automatically removed once its corresponding client object is removed.