Using thread data

The thread-local scope is an implicit scope that contains variables that are available only to the thread, and exist only for the life of the thread. Any variable that you define inside the cfthread tag body without specifying a scope name prefix is in the thread local scope and cannot be accessed or modified by other threads.

To create a thread-local variable, assign the variable in the cfthread tag body without specifying a scope prefix, as in the following lines:

<cfset var index=1> 
<cfset index=1>

These two lines are equivalent, with one exception: If you use the var keyword, the assignment code must immediately follow the cfthread tag, before any other CFML tags.

The Thread scope contains thread-specific variables and metadata about the thread. Only the owning thread can write data to this scope, but the page thread and all other threads in a request can read the variable values in this scope. Thread scope data remains available until the page and all threads that started from the page finish, even if the page finishes before the threads complete processing.

To create a Thread scope variable, in the cfthread tag body, use the keyword Thread or the name of the thread (for example, myThread) as a prefix. the following examples of creating a Thread scope variable are equivalent:

<cfset Thread.myValue = 27> 
<cfset myThread.myValue = 27>

To access a thread’s Thread scope variables outside the thread, prefix the variable with the thread’s name, as in the following example:

<cfset nextValue=myThread.myValue + 1>

Thread scope variables are only available to the page that created the thread or to other threads created by that page. No other page can access the data. If one page must access another page’s Thread scope data, you must place the data in a database or file and access it from there.

The Thread scope of each thread is a subscope of a special scope, cfthread, that lasts as long as the request, or until the last thread that it starts completes, whichever is longer. Thus, if you have two threads, myThread1 and myThread2, you can access their Thread scopes as cfthread.myThread1 and cfthread.myThread2 until all threads and the request complete. In most cases, there is no need to use the cfthread scope directly. However, you can use the cfthread scope name in either of the following situations:

1. If you generate the thread name dynamically, you can avoid using the Evaluate function by using the cfthread scope with associative array notation, as the following code snippet shows:

   <cfset threadname="thread_#N#"> 
   ... 
   <!--- The following two lines are equivalent ---> 
   <cfset threadscopeForNthThread = cfthread[threadname] > 
   <cfset threadscopeForNthThread = Evaluate(threadname) >

2. If you have a thread with the same name as a Variables scope variable, you can access that thread’s Thread scope only by prefacing the Thread name with cfthread. Otherwise, you access the Variables scope variable, or get an error.

The Attributes scope contains attributes that are passed to the thread, either individually or in the attributeCollection attribute. The Attributes scope is available only within the thread and only for the life of the thread.

ColdFusion makes a complete (deep) copy of all the attribute variables before passing them to the thread; therefore, the values of the variables inside the thread are independent of the values of any corresponding variables in other threads, including the page thread. For example, if you pass a CFC instance as an attribute to a thread, the thread gets a complete new copy of the CFC, including the contents of its This scope at the time that you create the thread. Any changes made to the original CFC outside the thread, for example, by calling a CFC function, have no effect on the copy that is in the thread. Similarly, any changes to the CFC instance in the thread have no effect on the original CFC instance.

Copying the data ensures that the values passed to threads are thread-safe, because the attribute values cannot be changed by any other thread. If you do not want duplicate data, do not pass it to the thread as an attribute or in the attributeCollection attribute. Instead, keep the data in a scope that the thread can access. An example of an object that should not be passed to the thread as an attribute is a singleton CFC that should never be duplicated. The singleton CFC must be kept in some shared scope and accessed by threads. For more information, see the Using other scopes.

Because ColdFusion copies all attributes by value, you can have multiple threads, for example, threads created dynamically in a loop, that use the same attribute names, but where each thread gets a different value, as shown in the following code excerpt, which creates separate threads to copy each of several files in a directory:

<cfloop query="dir"> 
    <cfset threadname = "thread_" & #i#> 
    <cfset i=i+1> 
    <cfthread name="#threadname#" filename="#dir.name#"> 
        <cffile action="COPY" source="#src#\#filename#" 
            destination="#dest#\#filename#\"> 
    </cfthread> 
</cfloop>

Threads have access to all the ColdFusion scopes. All the threads run by a page share the same Variables and This scope. All the threads run in a request share the same Form, URL, Request, CGI, Cookie, Session, Application, Server and Client scopes. Be careful to lock access to these scopes if more than one thread could try to modify the data in the scopes; otherwise you can get deadlocks between threads. For more information, see Locking thread data and resource access.

Although a thread can access all the scopes, it might not be able to write to scopes like Session, Cookie, or Request after the request page processing completes.

If you do not specify a scope prefix on a variable inside a cfthread tag body, ColdFusion checks scopes in the following order to find the variable:

1. Function-local, in function definitions in the thread only

2. Thread-local

3. Attributes

4. Variables

5. Thread/cfthread

Other scopes are checked in the standard scope checking order.