<cfthread>

The cfthread tag enables you to create threads, independent streams of code execution, in your application.

You use this tag to run or end a thread, temporarily stop thread execution, or join together multiple threads.

You can pass in any additional attributes you need to, these are then available within the thread, in the attributes scope, which is useful for passing data into the thread.

In Lucee these attributes are passed by reference, unlike other CFML engines.

If you are using thread in cfscript, you can also access these via the arguments scope, but this is not recommended or compatible with other CFML engines.

Each thread has it's own unique set of debugging logs, which will not show up in the main pages, normal debugging report.

You can access this debugging data, inside the thread using <cfadmin action="getDebugData" returnVariable="data">.

This tag may have a body.

This tag is also supported within <cfscript>

<cfthread action=join|run|sleep|terminate type=daemon|task retryinterval=any duration=number name=string priority=string timeout=number ><!--- body --->[</cfthread>]
Attribute Description Default
action
string, optional

The action to take, one of the following values:

  • join - Makes the current thread wait until the thread or threads specified in the name attribute complete processing, or until the period specified in the timeout attribute passes, before continuing processing. If you don't specify a timeout and thread you are joining to doesn't finish, the current thread also cannot finish processing.
  • run - Creates a thread and starts it processing.
  • sleep - Suspends the current threads processing for the time specified by the duration attribute. This action is useful if one thread must wait for another thread to do processing without joining the threads.
  • terminate - Stops processing of the thread specified in the name attribute. If you terminate a thread, the thread scope includes an ERROR metadata structure with information about the termination.

run

type
string, optional

Type of the thread:

  • daemon (default) - executes as daemon of the current thread
  • task - executed by the task manager

daemon

retryinterval
any, optional

When type task, this attribute define an execution plan for additional tries of execution. You can define a single rule or multiple rules as an array.

Example single rule:

#{interval:createTimeSpan(0,0,0,5),tries:5}#

In this case Lucee replays the thread for a maximum of 5 times, when the execution fails, Lucee waits for 5 seconds before doing the next try.

Example multiple rules:

#[{interval:createTimeSpan(0,0,0,5),tries:5},{interval:createTimeSpan(0,0,0,10),tries:5}]#

In this case Lucee replays the thread for a maximum of 10 times, when the execution fails, 5 times every 5 seconds, then 5 times every 10 seconds.

Alias: retryintervall

duration
number, optional

(sleep) The number of milliseconds for which to suspend thread processing. (required)

name
string, optional

The name of the thread to which the action applies:

  • terminate The name of the thread to stop.
  • join The name of the thread or threads to join to the current thread.
  • run The name to use to identify the thread being created.

To specify multiple threads, use a comma-delimited list.

priority
string, optional

The priority level at which to run the thread.

The following values are valid: HIGH, LOW, NORMAL

Higher priority threads get more processing time than lower priority threads.

Page-level code, the code that is outside of cfthread tags, always has NORMAL priority. (optional, default=NORMAL)

timeout
number, optional

The number of milliseconds that the current thread waits for the thread or threads being joined to finish.

If any thread does not finish by the specified time, the current thread proceeds.

If the attribute value is 0, the default, the current thread continues waiting until all joining threads finish.

If the current thread is the page thread, the page continues waiting until the threads are joined, even if you specify a page timeout. (optional, default=0)

Examples

https://www.youtube.com/watch?v=oGUZRrcg9KE

See also