Add optional parallel eager loading

ModuleConfig.cfc

@@ -8,12 +8,14 @@ component {
 
 	function configure() {
 		settings = {
-			"defaultGrammar"               : "AutoDiscover@qb",
-			"defaultQueryOptions"          : {},
-			"preventDuplicateJoins"        : true,
-			"preventLazyLoading"           : false,
-			"refreshOnSaveFallback"        : true,
-			"lazyLoadingViolationCallback" : ( entity, relationName ) => {
+			"defaultGrammar"                 : "AutoDiscover@qb",
+			"defaultQueryOptions"            : {},
+			"parallelEagerLoadingMaxThreads" : 4,
+			"parallelEagerLoadingTimeout"    : 60000,
+			"preventDuplicateJoins"          : true,
+			"preventLazyLoading"             : false,
+			"refreshOnSaveFallback"          : true,
+			"lazyLoadingViolationCallback"   : ( entity, relationName ) => {
 				throw(
 					type    = "QuickLazyLoadingException",
 					message = "Attempted to lazy load the [#arguments.relationName#] relationship on the entity [#arguments.entity.mappingName()#] but lazy loading is disabled. This is usually caused by the N+1 problem and is a sign that you are missing an eager load."
@@ -54,6 +56,15 @@ component {
 	}
 
 	function onLoad() {
+		wirebox
+			.getInstance( "AsyncManager@coldbox" )
+			.newExecutor(
+				name           = "quick-parallel-eager-loading",
+				type           = "fixed",
+				threads        = max( 1, int( settings.parallelEagerLoadingMaxThreads ) ),
+				loadAppContext = true
+			);
+
 		binder
 			.map( alias = "QuickQB@quick", force = true )
 			.to( "#moduleMapping#.models.QuickQB" )
@@ -86,6 +97,11 @@ component {
 	}
 
 	function onUnload() {
+		var asyncManager = wirebox.getInstance( "AsyncManager@coldbox" );
+		if ( asyncManager.hasExecutor( "quick-parallel-eager-loading" ) ) {
+			asyncManager.deleteExecutor( "quick-parallel-eager-loading" );
+		}
+
 		var cacheBox = wirebox.getCachebox();
 		if ( cacheBox.cacheExists( settings.metadataCache.name ) ) {
 			cacheBox.getCache( settings.metadataCache.name ).clearAll();

models/BaseEntity.cfc

@@ -949,11 +949,11 @@ component accessors="true" {
 			overlay = overlay.previous;
 		}
 
-		var attributes = [];
+		var runtimeAttributes = [];
 		for ( var i = newestFirst.len(); i >= 1; i-- ) {
-			attributes.append( newestFirst[ i ] );
+			runtimeAttributes.append( newestFirst[ i ] );
 		}
-		return attributes;
+		return runtimeAttributes;
 	}
 
 	private void function registerRuntimeAttribute( required struct attribute ) {

models/ParallelEagerLoadingCoordinator.cfc

@@ -0,0 +1,56 @@
+/**
+ * Coordinates parallel eager-loading work on Quick's application-wide executor.
+ */
+component singleton {
+
+	property name="executor"       inject="executor:quick-parallel-eager-loading";
+	property name="controller"     inject="coldbox";
+	property name="requestService" inject="coldbox:requestService";
+
+	function init() {
+		variables.currentWorker = createObject( "java", "java.lang.ThreadLocal" ).init();
+		return this;
+	}
+
+	public any function submit( required any task ) {
+		return variables.executor.submit( arguments.task, "run" );
+	}
+
+	public any function getExecutor() {
+		return variables.executor;
+	}
+
+	public any function createWorkerRequestContext( required string workerName ) {
+		var sourceContext = variables.requestService.getContext();
+		var workerContext = createObject( "component", "coldbox.system.web.context.RequestContext" ).init(
+			properties = variables.controller.getConfigSettings(),
+			controller = variables.controller
+		);
+		workerContext.collectionAppend( structCopy( sourceContext.getCollection() ), true );
+		workerContext.collectionAppend(
+			structCopy( sourceContext.getPrivateCollection() ),
+			true,
+			true
+		);
+		workerContext.setPrivateValue( "__quickParallelWorkerContextId", arguments.workerName );
+		return workerContext;
+	}
+
+	public void function enterWorker( required string name ) {
+		variables.currentWorker.set( arguments.name );
+	}
+
+	public void function leaveWorker() {
+		variables.currentWorker.remove();
+	}
+
+	public boolean function isWorker() {
+		return !isNull( variables.currentWorker.get() );
+	}
+
+	public string function getWorkerName() {
+		var workerName = variables.currentWorker.get();
+		return isNull( workerName ) ? "" : workerName;
+	}
+
+}

models/ParallelEagerLoadingTask.cfc

@@ -0,0 +1,67 @@
+/**
+ * Retrieves the database rows for one prepared eager-loading relationship.
+ * Relationship preparation and entity hydration remain on the calling thread.
+ */
+component {
+
+	function init(
+		required struct plan,
+		required string name,
+		required any coordinator,
+		required any requestContext,
+		required any completionQueue
+	) {
+		variables.plan            = arguments.plan;
+		variables.name            = arguments.name;
+		variables.coordinator     = arguments.coordinator;
+		variables.requestContext  = arguments.requestContext;
+		variables.completionQueue = arguments.completionQueue;
+		return this;
+	}
+
+	public void function run() {
+		// ColdBox's BoxLang executor context retains the caller's request scope.
+		// Enter a fresh application request so concurrent workers cannot overwrite
+		// each other's ColdBox RequestContext.
+		if ( server.keyExists( "boxlang" ) ) {
+			runThreadInContext(
+				applicationName = getApplicationMetadata().name,
+				callback        = function() {
+					execute();
+				}
+			);
+			return;
+		}
+		execute();
+	}
+
+	private void function execute() {
+		var requestContextInstalled = false;
+		var workerEntered           = false;
+		try {
+			request.cb_requestContext = variables.requestContext;
+			requestContextInstalled   = true;
+			variables.coordinator.enterWorker( variables.name );
+			workerEntered = true;
+			variables.completionQueue.offer( {
+				"name"    : variables.name,
+				"success" : true,
+				"rows"    : variables.plan.relation.retrieveEagerRows()
+			} );
+		} catch ( any e ) {
+			variables.completionQueue.offer( {
+				"name"    : variables.name,
+				"success" : false,
+				"error"   : e
+			} );
+		} finally {
+			if ( workerEntered ) {
+				variables.coordinator.leaveWorker();
+			}
+			if ( requestContextInstalled ) {
+				structDelete( request, "cb_requestContext" );
+			}
+		}
+	}
+
+}