Lucee Tag Reference

<cfthread>

The `cfthread` tag enables concurrent execution through thread management in your CFML application. Threads are independent streams of code execution that allow you to perform multiple operations simultaneously, improving application performance and responsiveness. You can use this tag to: * **Create** new threads with custom processing * **Join** multiple threads together, synchronizing their execution * **Sleep** the current thread to pause execution * **Terminate** threads that need to be stopped immediately * **Interrupt** threads, allowing for cooperative stopping with resource cleanup Each thread gets its own isolated variable scope (`thread`) that persists across the thread's lifetime and can be accessed from other parts of your application.

Body

This tag may have a body.

Example

<cfthread
	[action=join|run|sleep|terminate|interrupt]
	[duration=number]
	[name=string]
	[priority=string]
	[retryinterval=any]
	[separatescopes=boolean]
	[throwonerror=boolean]
	[timeout=number]
	[type=daemon|task] ... >
[</cfthread>]
This tag is also supported within cfscript
<cfscript>
	thread
		[action=join|run|sleep|terminate|interrupt]
		[duration=number]
		[name=string]
		[priority=string]
		[retryinterval=any]
		[separatescopes=boolean]
		[throwonerror=boolean]
		[timeout=number]
		[type=daemon|task]... {
			[...]
	}
</cfscript>

Attributes

This tag has a fixed definition of attributes (see below). In addition it allows to use any additional attribute
Name Type Required Default Value Description
action string No run Specifies the operation to perform on the thread. Options include:
* **run** (default): Creates a new thread and begins execution immediately. The thread executes the code contained within the tag body.
* **join**: Synchronizes the current thread with one or more target threads, pausing execution until the specified threads complete or a timeout occurs. This enables coordinated workflows where operations depend on the results of multiple threads.
* **sleep**: Temporarily suspends the current thread's execution for the specified duration in milliseconds. This action is useful for rate-limiting, implementing delays, or yielding processing time to other threads without creating full thread dependencies.
* **terminate**: Forcibly stops the specified thread's execution immediately. This is a non-cooperative shutdown that may leave resources in an inconsistent state. When terminated, the thread scope will include an `ERROR` metadata structure with termination details.
* **interrupt**: Sets the interrupt status flag on the specified thread, requesting cooperative termination. If the thread is blocked in a `ThreadJoin`, `sleep`, or I/O operation, it will receive an `InterruptedException` and its interrupt status will be cleared. The thread can then perform cleanup operations before stopping, making this safer than `terminate` for most scenarios. 
duration number No The number of milliseconds to suspend thread processing when using `action="sleep"`. This parameter is required for the sleep action.
Typical use cases include adding delays between operations, implementing rate limiting or throttling, and simulating latency for testing purposes. 
name string No Specifies the target thread identifier(s). The usage depends on the `action` attribute:
* With `action="run"`: Defines the name to identify the new thread being created. This name becomes the key in the `thread` scope and must be unique within the application.
* With `action="join"`: Specifies which thread(s) the current thread should wait for. To join multiple threads, provide a comma-delimited list of thread names.
* With `action="terminate"` or `action="interrupt"`: Identifies the thread(s) to stop or interrupt.
Thread names should be descriptive of their purpose and follow a consistent naming convention for maintainability. 
priority string No Sets the execution priority level for the thread when using `action="run"`. Valid values are:
* **HIGH**: Thread receives more CPU time, suitable for critical operations
* **NORMAL**: Standard priority level (default)
* **LOW**: Thread receives less CPU time, suitable for background operations
Priority affects thread scheduling by the JVM but does not guarantee execution order. Higher priority threads generally get more processing time than lower priority ones, but this depends on the JVM implementation and system load.
Note that page-level code (outside of `cfthread` tags) always executes at `NORMAL` priority. 
retryinterval any No When `type="task"`, this attribute defines an execution plan for automatic retry attempts when thread execution fails. You can specify either a single retry rule or multiple rules as an array.
A single rule specifies the interval between retries and the number of retry attempts with a structure containing `interval` and `tries` keys. The `interval` is a timespan value defining the waiting period between retries, and `tries` is the number of retry attempts.
Multiple rules can be defined as an array of structures, each containing `interval` and `tries` keys. This allows for implementing progressive retry strategies with different intervals for different phases of the retry process. 
separatescopes boolean No Only applicable with `action="run"`. Controls whether the thread gets its own isolated copy of the caller's scopes or shares them directly. Defaults to `true`.
* When `true` (default): The thread receives a deep copy of the caller's scopes at thread creation time. Changes made within the thread do not affect the parent context, and vice versa. This provides isolation and prevents concurrency issues.
* When `false`: The thread directly accesses the caller's scopes. Changes made in the thread are immediately visible to the parent context. Use with caution as this can lead to race conditions and thread safety issues.
This attribute is useful when you need threads to share state, but requires careful synchronization to avoid data corruption. 
throwonerror boolean No false Only applicable with `action="join"`. Determines whether exceptions thrown in joined threads should propagate to the joining thread.
* When `true`: If any of the joined threads have encountered errors, the first error found will be thrown as an exception in the current thread. This allows for easier error detection by propagating errors up the call stack.
* When `false` (default): Errors in joined threads remain isolated in their respective thread scopes and won't affect the current thread's execution. You must explicitly check the thread status to identify errors.
This attribute is useful for implementing fail-fast behavior in situations where thread errors should immediately stop dependent operations. 
timeout number No When using `action="join"`, specifies the maximum time in milliseconds that the current thread will wait for the joined thread(s) to complete.
* If set to `0` (default): The current thread will wait indefinitely until all joining threads finish.
* If set to any positive number: The current thread will resume after the specified timeout, even if joined threads haven't completed.
This attribute prevents deadlocks and allows for graceful timeout handling in multi-threaded operations. When the current thread is the page thread, the page continues waiting until either the threads complete or the timeout expires, regardless of page timeout settings. 
type string No daemon Defines the thread execution model:
* **daemon** (default): Executes as a daemon thread of the current thread. Daemon threads do not prevent the application from shutting down when all non-daemon threads have completed.
* **task**: Executed by the Lucee task manager, which provides additional robustness features like retry mechanisms. Task threads are ideal for asynchronous operations that should continue even if the user request completes.