CFLib.org – Common Function Library Project

defer(job[, onSuccess][, onFailure][, onError][, onTerminate])

Last updated October 21, 2013

author

Adam Cameron

Version: 1 | Requires: CF10 | Library: UtilityLib

Description:
Hands-off a job to a thread and upon completion / failure / etc calls the provided event handlers.

Return Values:
A struct containing functions getStatus(), getThreadId() and terminate()

Example:

bigFileToProcess = "path/to/file";

deferredJob = defer(
	job		= function(){
		var someResult = "";
		var fileHandle = fileOpen(bigFileToProcess, "read");
		while (!fileIsEof(fileHandle)){
			var line = fileReadLine(fileHandle);
			// etc
		}
		fileClose(fileHandle); 
		return someResult;
	},
	onSuccess	= function(result){
		// will receive someResult, so do something with it
	},
	onFailure	= function(e){
		writeLog(file="someLogFIle", text="It didnae work because of #e.message#");
	}
);

Parameters:

Name Description Required
job The code to defer Yes
onSuccess Handler to run if job code completes without error No
onFailure Handler to run if job code errors No
onError Handler to run if defer() code errors No
onTerminate Handler to run if terminate is called No

Full UDF Source:

/**
 * A function to hand of a job to a separate thread
 * v1.0 by Adam Cameron
 * v1.1 by Adam Cameron (added getThreadId(), made thread names unique, fixed logic error around onError())
 * 
 * @param job 	 The code to defer (Required)
 * @param onSuccess 	 Handler to run if job code completes without error (Optional)
 * @param onFailure 	 Handler to run if job code errors (Optional)
 * @param onError 	 Handler to run if defer() code errors (Optional)
 * @param onTerminate 	 Handler to run if terminate is called (Optional)
 * @return A struct containing functions getStatus(), getThreadId() and terminate() 
 * @author Adam Cameron (dac.cfml@gmail.com) 
 * @version 1.1, October 21, 2013 
 */
public struct function defer(required function job, function onSuccess, function onFailure, function onError, function onTerminate){
	var threadId = "deferredThread_#createUuid()#";

	local[threadId] = "";

	try {
		cfthread.status = "Running";
		thread name=threadId action="run" attributecollection=arguments {
			try {
				successData.result = job();
				cfthread.status = "Completed";
				if (structKeyExists(attributes, "onSuccess")){
					onSuccess(successData);
				}
			} catch (any e){
				cfthread.status = "Failed";
				if (structKeyExists(attributes, "onFailure")){
					onFailure(e);
				}else{
					rethrow;
				}
			}
		}
	} catch (any e){
		cfthread.status = "Errored";
		if (structKeyExists(arguments, "onError")){
			onError(e);
		}else{
			rethrow;
		}
	}
	return {
		getStatus = function(){
			return cfthread.status;
		},
		getThreadId = function(){
			return threadId;
		},
		terminate = function(){
			if (cfthread.status == "Running"){
				thread name=threadId action="terminate";
				cfthread.status = "Terminated";
				if (isDefined("onTerminate")){
					onTerminate();
				}
			}
		}
	};
}
blog comments powered by Disqus

Search CFLib.org


Latest Additions

Kevin Cotton added
date2ExcelDate
May 5, 2016

Raymond Camden added
CapFirst
April 25, 2016

Chris Wigginton added
loremIpsum
January 18, 2016

Gary Stanton added
calculateArrival...
November 19, 2015

Sebastiaan Naafs - van Dijk added
getDaysInQuarter
November 13, 2015

Created by Raymond Camden / Design by Justin Johnson