►The Racket Reference
►10 Concurrency and Parallelism
▼10.3 Thread-Local Storage
10.3.1 Thread Cells
10.3.2 Parameters
On this page:
thread-cell?
make-thread-cell
thread-cell-ref
thread-cell-set!
current-preserved-thread-cell-values
  top← prev  up  next → 
10.3.1 Thread Cells

A thread cell contains a thread-specific value; that is, it contains a specific value for each thread, but it may contain different values for different threads. A thread cell is created with a default value that is used for all existing threads. When the cell’s content is changed with thread-cell-set!, the cell’s value changes only for the current thread. Similarly, thread-cell-ref obtains the value of the cell that is specific to the current thread.

A thread cell’s value can be preserved, which means that when a new thread is created, the cell’s initial value for the new thread is the same as the creating thread’s current value. If a thread cell is non-preserved, then the cell’s initial value for a newly created thread is the default value (which was supplied when the cell was created).

Within the current thread, the current values of all preserved threads cells can be captured through current-preserved-thread-cell-values. The captured set of values can be imperatively installed into the current thread through another call to current-preserved-thread-cell-values. The capturing and restoring threads can be different.

(thread-cell? v) → boolean?
  v : any/c
Returns #t if v is a thread cell, #f otherwise.

(make-thread-cell v [preserved?]) → thread-cell?
  v : any/c
  preserved? : any/c = #f
Creates and returns a new thread cell. Initially, v is the cell’s value for all threads. If preserved? is true, then the cell’s initial value for a newly created threads is the creating thread’s value for the cell, otherwise the cell’s value is initially v in all future threads.

(thread-cell-ref cell) → any
  cell : thread-cell?
Returns the current value of cell for the current thread.

(thread-cell-set! cell v) → any
  cell : thread-cell?
  v : any/c
Sets the value in cell to v for the current thread.

Examples:

> (define cnp (make-thread-cell '(nerve) #f))
> (define cp (make-thread-cell '(cancer) #t))
> (thread-cell-ref cnp)

'(nerve)

> (thread-cell-ref cp)

'(cancer)

> (thread-cell-set! cnp '(nerve nerve))
> (thread-cell-set! cp '(cancer cancer))
> (thread-cell-ref cnp)

'(nerve nerve)

> (thread-cell-ref cp)

'(cancer cancer)

> (define ch (make-channel))
> (thread (lambda ()
            (channel-put ch (thread-cell-ref cnp))
            (channel-put ch (thread-cell-ref cp))
            (channel-get ch)
            (channel-put ch (thread-cell-ref cp))))

#<thread>

> (channel-get ch)

'(nerve)

> (channel-get ch)

'(cancer cancer)

> (thread-cell-set! cp '(cancer cancer cancer))
> (thread-cell-ref cp)

'(cancer cancer cancer)

> (channel-put ch 'ok)
> (channel-get ch)

'(cancer cancer)

(current-preserved-thread-cell-values) → any
(current-preserved-thread-cell-values thread-cell-vals) → void?
  thread-cell-vals : any/c
When called with no arguments, this procedure produces a thread-cell-vals that represents the current values (in the current thread) for all preserved thread cells.

When called with a thread-cell-vals generated by a previous call to current-preserved-thread-cell-values, the values of all preserved thread cells (in the current thread) are set to the values captured in thread-cell-vals; if a preserved thread cell was created after thread-cell-vals was generated, then the thread cell’s value for the current thread reverts to its initial value.

  top← prev  up  next →