Work-in-Progress on PL/Java refactoring, API modernization

pljava-api/src/main/java/org/postgresql/pljava/Lifespan.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2022 Tada AB and other contributors, as listed below.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the The BSD 3-Clause License
+ * which accompanies this distribution, and is available at
+ * http://opensource.org/licenses/BSD-3-Clause
+ *
+ * Contributors:
+ *   Chapman Flack
+ */
+package org.postgresql.pljava;
+
+import org.postgresql.pljava.model.MemoryContext; // javadoc
+import org.postgresql.pljava.model.ResourceOwner; // javadoc
+
+/**
+ * Model of any notional object in PostgreSQL or PL/Java that has a definite
+ * temporal existence, with a detectable end, and so can be used to scope the
+ * lifetime of any PL/Java object that has corresponding native resources.
+ *<p>
+ * A {@code Lifespan} generalizes over assorted classes that can play that role,
+ * such as PostgreSQL's {@link ResourceOwner ResourceOwner} and
+ * {@link MemoryContext MemoryContext}. {@code MemoryContext} may see the most
+ * use in PL/Java, as the typical reason to scope the lifetime of some PL/Java
+ * object is that it refers to some allocation of native memory.
+ *<p>
+ * The invocation of a PL/Java function is also usefully treated as a resource
+ * owner. It is reasonable to depend on the objects passed in the function call
+ * to remain usable as long as the call is on the stack, if no other explicit
+ * lifespan applies.
+ *<p>
+ * Java's incubating foreign function and memory API will bring a
+ * {@code ResourceScope} object for which some relation to a PL/Java
+ * {@code Lifespan} can probably be defined.
+ *<p>
+ * The history of PostgreSQL <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=HEAD"
+>MemoryContext</a>s
+ * (the older mechanism, appearing in PostgreSQL 7.1), and <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/resowner/README;hb=HEAD"
+>ResourceOwner</a>s
+ * (introduced in 8.0) is interesting. As the latter's {@code README} puts it,
+ * <q>The design of the ResourceOwner API is modeled on our MemoryContext API,
+ * which has proven very flexible and successful ... It is tempting to consider
+ * unifying ResourceOwners and MemoryContexts into a single object type, but
+ * their usage patterns are sufficiently different ...."</q>
+ *<p>
+ * Only later, in PostgreSQL 9.5, did {@code MemoryContext} gain a callback
+ * mechanism for detecting reset or delete, with which it also becomes usable
+ * as a kind of lifespan under PL/Java's broadened view of the concept.
+ * While not <q>unifying ResourceOwners and MemoryContexts into a single
+ * object type</q>, PL/Java here makes them both available as subtypes of a
+ * common interface, so either can be chosen to place an appropriate temporal
+ * scope on a PL/Java object.
+ */
+public interface Lifespan
+{
+}

pljava-api/src/main/java/org/postgresql/pljava/model/Attribute.java

@@ -38,4 +38,5 @@ public interface Attribute
 	RegClass CLASS = formObjectId(RegClass.CLASSID, AttributeRelationId);
 
 	RegType type();
+	short length();
 }

pljava-api/src/main/java/org/postgresql/pljava/model/CatalogObject.java

@@ -551,5 +551,47 @@ RegClass.Known<T> formClassIdImpl(
 		protected static final int DEFAULT_COLLATION_OID = 100;
 		protected static final int       C_COLLATION_OID = 950;
 		protected static final int   POSIX_COLLATION_OID = 951;
+
+		/*
+		 * These magic numbers are assigned here to allow the various well-known
+		 * PostgreSQL ResourceOwners to be retrieved without a proliferation of
+		 * methods on the factory interface. These are arbitrary array indices,
+		 * visible also to JNI code through the generated headers just as
+		 * described above. The native initialization method may create,
+		 * for example, an array of ByteBuffers that window the corresponding
+		 * PostgreSQL globals, ordered according to these indices. The Java code
+		 * implementing resourceOwner() can be ignorant of these specific values
+		 * and simply use them to index the array. HOWEVER, it does know that
+		 * the first one, index 0, refers to the current resource owner.
+		 */
+		protected static final int RSO_Current        = 0; // must be index 0
+		protected static final int RSO_CurTransaction = 1;
+		protected static final int RSO_TopTransaction = 2;
+		protected static final int RSO_AuxProcess     = 3;
+
+		protected abstract ResourceOwner resourceOwner(int which);
+
+		/*
+		 * Same as above but for the well-known PostgreSQL MemoryContexts.
+		 * Again, the implementing code knows index 0 is for the current one.
+		 */
+		protected static final int MCX_CurrentMemory  = 0; // must be index 0
+		protected static final int MCX_TopMemory      = 1;
+		protected static final int MCX_Error          = 2;
+		protected static final int MCX_Postmaster     = 3;
+		protected static final int MCX_CacheMemory    = 4;
+		protected static final int MCX_Message        = 5;
+		protected static final int MCX_TopTransaction = 6;
+		protected static final int MCX_CurTransaction = 7;
+		protected static final int MCX_Portal         = 8;
+		/*
+		 * A long-lived, never-reset context created by PL/Java as a child of
+		 * TopMemoryContext.
+		 */
+		protected static final int MCX_JavaMemory     = 9;
+
+		protected abstract MemoryContext memoryContext(int which);
+
+		protected abstract MemoryContext upperMemoryContext();
 	}
 }

pljava-api/src/main/java/org/postgresql/pljava/model/MemoryContext.java

@@ -0,0 +1,149 @@
+/*
+ * Copyright (c) 2022 Tada AB and other contributors, as listed below.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the The BSD 3-Clause License
+ * which accompanies this distribution, and is available at
+ * http://opensource.org/licenses/BSD-3-Clause
+ *
+ * Contributors:
+ *   Chapman Flack
+ */
+package org.postgresql.pljava.model;
+
+import org.postgresql.pljava.Lifespan;
+
+import static org.postgresql.pljava.model.CatalogObject.Factory.*;
+
+/**
+ * A PostgreSQL {@code MemoryContext}, which is usable as a PL/Java
+ * {@link Lifespan Lifespan} to scope the lifetimes of PL/Java objects
+ * (as when they depend on native memory allocated in the underlying context).
+ *<p>
+ * The {@code MemoryContext} API in PostgreSQL is described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=HEAD"
+>here</a>.
+ *<p>
+ * Static getters for the globally known contexts are spelled and capitalized
+ * as they are in PostgreSQL.
+ */
+public interface MemoryContext extends Lifespan
+{
+	/**
+	 * The top level of the context tree, of which every other context is
+	 * a descendant.
+	 *<p>
+	 * Used as described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=REL_14_0#l179"
+>here</a>.
+	 */
+	MemoryContext TopMemoryContext =
+		INSTANCE.memoryContext(MCX_TopMemory);
+
+	/**
+	 * The "current" memory context, which supplies all allocations made by
+	 * PostgreSQL {@code palloc} and related functions that do not explicitly
+	 * specify a context.
+	 *<p>
+	 * Used as described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=REL_14_0#l72"
+>here</a>.
+	 */
+	static MemoryContext CurrentMemoryContext()
+	{
+		return INSTANCE.memoryContext(MCX_CurrentMemory);
+	}
+
+	/**
+	 * Getter method equivalent to the final
+	 * {@link #TopMemoryContext TopMemoryContext} field, for consistency with
+	 * the other static getters.
+	 */
+	static MemoryContext TopMemoryContext()
+	{
+		return TopMemoryContext;
+	}
+
+	/**
+	 * Holds everything that lives until end of the top-level transaction.
+	 *<p>
+	 * Can be appropriate when a specification, for example JDBC, provides that
+	 * an object should remain valid for the life of the transaction.
+	 *<p>
+	 * Uses are described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=REL_14_0#l217"
+>here</a>.
+	 */
+	static MemoryContext TopTransactionContext()
+	{
+		return INSTANCE.memoryContext(MCX_TopTransaction);
+	}
+
+	/**
+	 * The same as {@link #TopTransactionContext() TopTransactionContext} when
+	 * in a top-level transaction, but different in subtransactions (such as
+	 * those associated with PL/Java savepoints).
+	 *<p>
+	 * Used as described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=REL_14_0#l226"
+>here</a>.
+	 */
+	static MemoryContext CurTransactionContext()
+	{
+		return INSTANCE.memoryContext(MCX_CurTransaction);
+	}
+
+	/**
+	 * Context of the currently active execution portal.
+	 *<p>
+	 * Used as described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=REL_14_0#l242"
+>here</a>.
+	 */
+	static MemoryContext PortalContext()
+	{
+		return INSTANCE.memoryContext(MCX_Portal);
+	}
+
+	/**
+	 * A permanent context switched into for error recovery processing.
+	 *<p>
+	 * Used as described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/mmgr/README;hb=REL_14_0#l247"
+>here</a>.
+	 */
+	static MemoryContext ErrorContext()
+	{
+		return INSTANCE.memoryContext(MCX_Error);
+	}
+
+	/**
+	 * A long-lived, never-reset context created by PL/Java as a child of
+	 * {@code TopMemoryContext}.
+	 *<p>
+	 * Perhaps useful for PL/Java-related allocations that will be long-lived,
+	 * or managed only from the Java side, as a way of accounting for them
+	 * separately, as opposed to just putting them in {@code TopMemoryContext}.
+	 * It hasn't been used consistently even in the historical PL/Java
+	 * code base, and should perhaps be a candidate for deprecation (or for
+	 * a thorough code review to establish firmer guidelines for its use).
+	 */
+	static MemoryContext JavaMemoryContext()
+	{
+		return INSTANCE.memoryContext(MCX_JavaMemory);
+	}
+
+	/**
+	 * The "upper executor" memory context (that is, the context on entry, prior
+	 * to any use of SPI) associated with the current (innermost) PL/Java
+	 * function invocation.
+	 *<p>
+	 * This is "precisely the right context for a value returned" from a
+	 * function that uses SPI, as described
+	 * <a href="https://www.postgresql.org/docs/14/spi-memory.html">here</a>.
+	 */
+	static MemoryContext UpperMemoryContext()
+	{
+		return INSTANCE.upperMemoryContext();
+	}
+}

pljava-api/src/main/java/org/postgresql/pljava/model/ResourceOwner.java

@@ -0,0 +1,53 @@
+/*
+ * Copyright (c) 2022 Tada AB and other contributors, as listed below.
+ *
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the The BSD 3-Clause License
+ * which accompanies this distribution, and is available at
+ * http://opensource.org/licenses/BSD-3-Clause
+ *
+ * Contributors:
+ *   Chapman Flack
+ */
+package org.postgresql.pljava.model;
+
+import org.postgresql.pljava.Lifespan;
+
+import org.postgresql.pljava.model.CatalogObject.Factory;
+
+import static org.postgresql.pljava.model.CatalogObject.Factory.*;
+
+/**
+ * The representation of a PostgreSQL {@code ResourceOwner}, usable as
+ * a PL/Java {@link Lifespan Lifespan}.
+ *<p>
+ * The {@code ResourceOwner} API in PostgreSQL is described <a href=
+"https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/backend/utils/resowner/README;hb=HEAD"
+>here</a>.
+ *<p>
+ * PostgreSQL invokes callbacks in phases when a {@code ResourceOwner}
+ * is released, and all of its built-in consumers get notified before
+ * loadable modules (like PL/Java) for each phase in turn. The release
+ * behavior of this PL/Java instance is tied to the
+ * {@code RESOURCE_RELEASE_LOCKS} phase of the underlying PostgreSQL object,
+ * and therefore occurs after all of the built-in PostgreSQL lock-related
+ * releases, but before any of the built-in stuff released in the
+ * {@code RESOURCE_RELEASE_AFTER_LOCKS} phase.
+ */
+public interface ResourceOwner extends Lifespan
+{
+	static ResourceOwner CurrentResourceOwner()
+	{
+		return INSTANCE.resourceOwner(RSO_Current);
+	}
+
+	static ResourceOwner CurTransactionResourceOwner()
+	{
+		return INSTANCE.resourceOwner(RSO_CurTransaction);
+	}
+
+	static ResourceOwner TopTransactionResourceOwner()
+	{
+		return INSTANCE.resourceOwner(RSO_TopTransaction);
+	}
+}

pljava-api/src/main/java/org/postgresql/pljava/model/package-info.java

@@ -93,6 +93,14 @@
  * methods on {@link Database Database} and {@link RegCollation RegCollation}.
  * The one in use on the server (an often-needed value) is exposed by the
  * {@link CharsetEncoding#SERVER_ENCODING SERVER_ENCODING} static.
+ *<h2>Lifespan subinterfaces</h2>
+ * Some PL/Java objects correspond to certain native structures in PostgreSQL
+ * and therefore must not be used beyond the native structures' lifespan.
+ * {@link Lifespan Lifespan} abstractly models any object in PostgreSQL that
+ * can be used to define, and detect the end of, a native-object lifespan.
+ * Two interfaces in this package that extend it and model specific PostgreSQL
+ * objects with that ability are {@link MemoryContext MemoryContext} and
+ * {@link ResourceOwner ResourceOwner}.
  *<h2>TupleTableSlot, TupleDescriptor, and Adapter</h2>
  *<p>
  * {@code TupleTableSlot} in PostgreSQL is a flexible abstraction that can
@@ -136,3 +144,4 @@
 package org.postgresql.pljava.model;
 
 import org.postgresql.pljava.Adapter;
+import org.postgresql.pljava.Lifespan;

pljava-so/src/main/c/Backend.c

@@ -757,7 +757,7 @@ static void initsequencer(enum initstage is, bool tolerant)
 					"and \"pljava-api.jar\" files, separated by the correct "
 					"path separator for this platform.")
 					));
-			pljava_DualState_unregister();
+			pljava_ResourceOwner_unregister();
 			_destroyJavaVM(0, 0);
 			goto check_tolerant;
 		}