Design of PGX API

Fundamentally, PGX is designed for server-client execution. It assumes the following situations:

• Multiple clients may concurrently be accessing a single running instance of PGX, sharing its resources. Each client needs to maintain its own isolated workspace (session).
• Graph and property data can be large in size; therefore, that data only resides on the server side.
• Some graph analysis may take a significant amount of time.
• Clients may not reside in the same address space (JVM) as PGX; in fact, clients may not even be Java applications.

The design of the PGX API reflects consideration of these situations.

Client Sessions

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.

Asynchronous Execution

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 Direct References

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.

• The client might not be in the same JVM as the server
• The graph instance might be shared by multiple clients

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.

Resource Management Considerations

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.

• Session time out. In some cases, the PGX server will remove the session and all its data automatically. This can occur when a client fails to destroy either the data or its session, or if it doesn't hear from the session after a configurable timeout.