# 11.2.3 Semaphores
> ```racket
> ( define ( server input-channel output-channel ) ( thread ( lambda ( ) ( define ( get ) ( async-channel-get input-channel ) ) ( define ( put x ) ( async-channel-put output-channel x ) ) ( define ( do-large-computation ) ( sqrt 9 ) ) ( let loop ( [ data ( get ) ] ) ( case data [ ( quit ) ( void ) ] [ ( add ) ( begin ( put ( + 1 ( get ) ) ) ( loop ( get ) ) ) ] [ ( long ) ( begin ( put ( do-large-computation ) ) ( loop ( get ) ) ) ] ) ) ) ) ) ( define to-server ( make-async-channel ) ) ( define from-server ( make-async-channel ) )
> > ( server to-server from-server )
> #<thread>
> > ( async-channel? to-server )
> #t
> > ( printf "Adding 1 to 4\n" )
> Adding 1 to 4
> > ( async-channel-put to-server ' add )
> > ( async-channel-put to-server 4 )
> > ( printf "Result is ~a\n" ( async-channel-get from-server ) )
> Result is 5
> > ( printf "Ask server to do a long computation\n" )
> Ask server to do a long computation
> > ( async-channel-put to-server ' long )
> > ( printf "I can do other stuff\n" )
> I can do other stuff
> > ( printf "Ok, computation from server is ~a\n" ( async-channel-get from-server ) )
> Ok, computation from server is 3
> > ( async-channel-put to-server ' quit )
> ```


##### 11.2.4.2 Contracts and Impersonators on Asynchronous Channels
> ```
(async-channel/c c)  →  contract?
  c : contract?
```
Returns a contract that recognizes asynchronous channels. Values put into or retrieved from the channel must match c.

If the c argument is a flat contract or a chaperone contract, then the result will be a chaperone contract. Otherwise, the result will be an impersonator contract.

When an async-channel/c contract is applied to an asynchronous channel, the result is not eq? to the input. The result will be either a chaperone or impersonator of the input depending on the type of contract.

> ```
(impersonate-async-channel channel
    get-proc
    put-proc
    prop
    prop-val ...
    ...)

   →   (and/c async-channel? impersonator?)
  channel : async-channel?
  get-proc : (any/c .  →  . any/c)
  put-proc : (any/c .  →  . any/c)
  prop : impersonator-property?
  prop-val : any```

Returns an impersonator of channel, which redirects the [async-channel-get](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._async-channel-get%29%29) and [async-channel-put](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._async-channel-put%29%29) operations.

The get-proc must accept the value that [async-channel-get](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._async-channel-get%29%29) produces on channel; it must produce a replacement value, which is the result of the get operation on the impersonator.

The put-proc must accept the value passed to [async-channel-put](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._async-channel-put%29%29) called on channel; it must produce a replacement value, which is the value passed to the put procedure called on the original channel.

The get-proc and put-proc procedures are called for all operations that get or put values from the channel, not just [async-channel-get](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._async-channel-get%29%29) and [async-channel-put](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._async-channel-put%29%29).

Pairs of prop and prop-val (the number of arguments to [impersonate-async-channel](#%28def._%28%28lib._racket%2Fasync-channel..rkt%29._impersonate-async-channel%29%29) must be odd) add [impersonator properties](chaperones.html#%28tech._impersonator._property%29) or override [impersonator property](chaperones.html#%28tech._impersonator._property%29) values of channel.

> ```
(chaperone-async-channel channel
    get-proc
    put-proc
    prop
    prop-val ...
    ...)

  →  (and/c async-channel? chaperone?)
  channel : async-channel?
  get-proc : (any/c .  →  . any/c)
  put-proc : (any/c .  →  . any/c)
  prop : impersonator-property?
  prop-val : any
```


# 11.2.3 Semaphores
(parameter)	→```
Returns #t if v is a [thread cell](eval-model.html#%28tech._thread._cell%29), #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
```
(nerve)	→
(-> current-preserved-thread-cell-values thread-cell-vals)```

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](#%28def._%28%28quote._~23~25kernel%29._current-preserved-thread-cell-values%29%29), 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.

> ```
(thread-cell-values? v)  →  boolean?
  v : any/c
```
(parameter)	→
(-> or/c (any/c . → . any) #f)```


# 11.2.3 Semaphores
Returns a new parameter procedure. The value of the parameter is initialized to v in all threads.
If guard is not #f, it is used as the parameter’s guard procedure. A guard procedure takes one argument. Whenever the parameter procedure is applied to an argument, the argument is passed on to the guard procedure. The result returned by the guard procedure is used as the new parameter value. A guard procedure can raise an exception to reject a change to the parameter’s value. The guard is not applied to the initial v.
The name argument is used as the parameter procedure’s name as reported by [object-name](inspectors.html#%28def._%28%28quote._~23~25kernel%29._object-name%29%29), and realm is used as the reported as reported by [procedure-realm](procedures.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._procedure-realm%29%29).
Changed in version 7.4.0.6 of package base: Added the name argument.
Changed in version 8.4.0.2: Added the realm argument.
> ```
syntax
(parameterize ([parameter-expr value-expr] ...)
> body ...+ )
   parameter-expr   :   parameter?


# 11.2.3 Semaphores
```
(interleaved)	→```

Analogous to [let*](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%2A%29%29) compared to [let](let.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._let%29%29), [parameterize*](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%2A%29%29) is the same as a nested series of single-parameter [parameterize](#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._parameterize%29%29) forms.

> ```
(parameter)	→
(-> any/c . → . any)
```
Returns a parameter procedure that sets or retrieves the same value as parameter, but with:
-  guard applied when setting the parameter (before any guard associated with parameter), and
-  wrap applied when obtaining the parameter’s value.
The name argument is used as the parameter procedure’s name as reported by object-name, and realm is used as the reported as reported by procedure-realm. Supply values for guard and wrap if the goal is merely to replace the name or realm of parameter.
See also chaperone-procedure, which can also be used to guard parameter procedures.
Changed in version 8.15.0.4 of package base: Added the name and realm arguments.
> ```
(parameter? v)   →   boolean?
  v : any/c```
Returns #t if v is a parameter procedure, #f otherwise.
> ```
(parameter-procedure=? a b) → boolean?
  a : parameter?
  b : parameter?


# 11.2.3 Semaphores
```
(current-parameterization)	→```

Returns the current continuation’s [parameterization](eval-model.html#%28tech._parameterization%29).

> ```
(call-with-parameterization   parameterization
    thunk)    →    any

  parameterization : parameterization?
  thunk : (  →   any)
```
Calls thunk (via a tail call) with parameterization as the current parameterization.
> ```
(parameterization? v)   →   boolean?
  v : any/c```
Returns #t if v is a [parameterization](eval-model.html#%28tech._parameterization%29) returned by [current-parameterization](#%28def._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._current-parameterization%29%29), #f otherwise.
------------------------------------------------------------------------


# 11.4 Futures


### 11.4 Futures
> > > <img src="finger.png" width="24" height="24" alt="+" />[Parallelism with Futures](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=parallelism.html%23%2528part._effective-futures%2529&version=8.18.0.13) in [The Racket Guide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=index.html&version=8.18.0.13) introduces futures.
|                                                                                |                                                                                |
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/future]()) |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |
The bindings documented in this section are provided by the [racket/future]() and [racket](index.html) libraries, but not [racket/base](index.html).


# 11.4 Futures
> > > Support for parallelism via [future](#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29) is normally enabled for all platforms in the [CS](implementations.html#%28tech._c%29) implementation of Racket. In the [BC](implementations.html#%28tech._bc%29) implementation, support for parallelism is enabled by default for Windows, Linux x86/x86_64, and Mac OS x86/x86_64. To enable support for other platforms building Racket [BC](implementations.html#%28tech._bc%29), use --enable-futures with configure.
The [future](#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29) and [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29) functions from [racket/future]() provide access to parallelism as supported by the hardware and operating system. In contrast to [thread](threads.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._thread%29%29), which provides concurrency for arbitrary computations without parallelism, [future](#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29) provides parallelism. A future executes its work in parallel (assuming that support for parallelism is available) until it detects an attempt to perform an operation that cannot run safely in parallel. Similarly, work in a future is suspended if it depends in some way on the current continuation, such as raising an exception. Operations that suspend a future are blocking operations. A suspended computation for a future is resumed when [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29) is applied to the future.


# 11.4 Futures
“Safe” parallel execution of a future means that all operations provided by the system must be able to enforce contracts and produce results as documented. “Safe” does not preclude concurrent access to mutable data that is visible in the program. For example, a computation in a future might use [set!](set_.html#%28form._%28%28quote._~23~25kernel%29._set%21%29%29) to modify a shared variable, in which case concurrent assignment to the variable can be visible in other futures and threads. Furthermore, guarantees about the visibility of effects and ordering are determined by the operating system and hardware—which rarely support, for example, the guarantee of sequential consistency that is provided for [thread](threads.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._thread%29%29)-based concurrency; see also [Machine Memory Order](memory-order.html). A system operation that seems obviously safe may have an internal implementation that cannot run in parallel; see [Parallelism with Futures](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=parallelism.html%23%2528part._effective-futures%2529&version=8.18.0.13) in [The Racket Guide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=index.html&version=8.18.0.13) for more discussion and an introduction to using [future-visualizer](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?tag=%28mod-path._.%27future-visualizer.%27%29&version=8.18.0.13)) to understand the behavior of system operations.


# 11.4 Futures
A future never runs in parallel if all of the [custodians](eval-model.html#%28tech._custodian%29) that allow its creating thread to run are shut down. Such futures can execute through a call to [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29), however.


#### 11.4.1 Creating and Touching Futures
> ```
(future thunk)  →  future?
  thunk : (  →   any)
(touch f)  →  any
  f : future?
```
The future procedure returns a future value that encapsulates thunk. The touch function forces the evaluation of the thunk inside the given future, returning the values produced by thunk. After touch forces the evaluation of a thunk, the resulting values are retained by the future in place of thunk, and additional touches of the future return those values.

Between a call to future and touch for a given future, the given thunk may run speculatively in parallel to other computations, as described above.

Example:

> ```racket
> > ( let ( [ f ( future ( lambda ( ) ( + 1 2 ) ) ) ] ) ( list ( + 3 4 ) ( touch f ) ) )
> '(7 3)
> ```

> ```
(futures-enabled?) → boolean?```

Returns whether parallel support for futures is enabled in the current Racket configuration.

> ```
(current-future)	→
(-> or/c #f future?)
```
Returns the descriptor of the future whose thunk execution is the current continuation; that is, if a future descriptor f is returned, (touch f) will produce the result of the current continuation. If a future thunk itself uses touch, future-thunk executions can be nested, in which case the descriptor of the most immediately executing future is returned. If the current continuation does not return to the touch of any future, the result is #f.
> ```
(future? v)   →   boolean?
  v : any/c```
Returns #t if v is a future value, #f otherwise.
> ```
(would-be-future thunk)  →  future?
  thunk : (  →   any)


# 11.4 Futures
```
Returns a future that never runs in parallel, but that consistently logs all potentially “unsafe” operations during the execution of the future’s thunk (i.e., operations that interfere with parallel execution).

With a normal future, certain circumstances might prevent the logging of unsafe operations. For example, when executed with debug-level logging,

> ```racket
> ( touch ( future ( lambda ( )
> ( printf "hello1" )
> ( printf "hello2" )
> ( printf "hello3" ) ) ) )
> ```

might log three messages, one for each printf invocation. However, if the touch is performed before the future has a chance to start running in parallel, the future thunk evaluates in the same manner as any ordinary thunk, and no unsafe operations are logged. Replacing future with would-be-future ensures the logging of all three calls to printf.

> ```
(processor-count)   →   exact-positive-integer?```

Returns the number of parallel computation units (e.g., processors or cores) that are available on the current machine.

This is the same binding as available from [racket/place](places.html).

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>([for/async](#%28form._%28%28lib._racket%2Ffuture..rkt%29._for%2Fasync%29%29) (for-clause ...) body-or-break ... body)</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>([for*/async](#%28form._%28%28lib._racket%2Ffuture..rkt%29._for%2A%2Fasync%29%29) (for-clause ...) body-or-break ... body)</p></blockquote></td></tr></tbody></table></td></tr></tbody></table>

Like [for](for.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for%29%29) and [for*](for.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._for%2A%29%29), but each iteration of the body is executed in a separate [future](#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29), and the futures may be [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29)ed in any order.

#### 11.4.2 Future Semaphores

> ```
(make-fsemaphore init)  →  fsemaphore?
  init : exact-nonnegative-integer?
```


# 11.4 Futures
Creates and returns a new future semaphore with the counter initially set to init.
A future semaphore is similar to a plain semaphore, but future-semaphore operations can be performed safely in parallel (to synchronize parallel computations). In contrast, operations on plain semaphores are not safe to perform in parallel, and they therefore prevent a computation from continuing in parallel.
Beware of trying to use an fsemaphore to implement a lock. A future may run concurrently and in parallel to other futures, but a future that is not demanded by a Racket thread can be suspended at any time—such as just after it takes a lock and before it releases the lock. If you must share mutable data among futures, lock-free data structures are generally a better fit.
> ```
(fsemaphore? v)   →   boolean?
  v : any/c```
Returns #t if v is an [future semaphore](#%28tech._future._semaphore%29) value, #f otherwise.
> ```
(parameter)	→
```
(parameter)	→```

Blocks until the internal counter for fsema is non-zero. When the counter is non-zero, it is decremented and [fsemaphore-wait](#%28def._%28%28lib._racket%2Ffuture..rkt%29._fsemaphore-wait%29%29) returns [#<void>](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.18.0.13).

> ```
(fsemaphore-try-wait? fsema)  →  boolean?
  fsema : fsemaphore?
```


# 11.4 Futures
Like fsemaphore-wait, but fsemaphore-try-wait? never blocks execution. If fsema’s internal counter is zero, fsemaphore-try-wait? returns #f immediately without decrementing the counter. If fsema’s counter is positive, it is decremented and #t is returned.
> ```
(fsemaphore-count fsema)   →   exact-nonnegative-integer?
  fsema : fsemaphore?```
Returns fsema’s current internal counter value.


#### 11.4.3 Future Performance Logging
Racket traces use logging (see [Logging](logging.html)) extensively to report information about how futures are evaluated. Logging output is useful for debugging the performance of programs that use futures.
Though textual log output can be viewed directly (or retrieved in code via [trace-futures](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=future-visualizer&rel=futures-trace.html%23%2528form._%2528%2528lib._future-visualizer%252Ftrace..rkt%2529._trace-futures%2529%2529&version=8.18.0.13)), it is much easier to use the graphical profiler tool provided by [future-visualizer](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?tag=%28mod-path._.%27future-visualizer.%27%29&version=8.18.0.13).
Future events are logged with the topic 'future. In addition to its string message, each event logged for a future has a data value that is an instance of a [future-event](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=future-visualizer&rel=futures-trace.html%23%2528def._%2528%2528lib._future-visualizer%252Ftrace..rkt%2529._future-event%2529%2529&version=8.18.0.13) [prefab](structures.html#%28tech._prefab%29) structure:
> ```racket
> ( struct future-event ( future-id proc-id action time prim-name user-data )
> #:prefab )
> ```
The future-id field is an exact integer that identifies a future, or it is #f when action is 'missing. The future-id field is particularly useful for correlating logged events.


# 11.4 Futures
The proc-id fields is an exact, non-negative integer that identifies a parallel process. Process 0 is the main Racket process, where all expressions other than future thunks evaluate.
The [time](time.html#%28form._%28%28lib._racket%2Fprivate%2Fmore-scheme..rkt%29._time%29%29) field is an inexact number that represents time in the same way as [current-inexact-milliseconds](time.html#%28def._%28%28quote._~23~25kernel%29._current-inexact-milliseconds%29%29).
The action field is a symbol:
-   'create: a future was created.
-   'complete: a future’s thunk evaluated successfully, so that [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29) will produce a value for the future immediately.
-   'start-work and 'end-work: a particular process started and ended working on a particular future.
-   'start-0-work: like 'start-work, but for a future thunk that for some structural reason could not be started in a process other than 0 (e.g., the thunk requires too much local storage to start).
-   'start-overflow-work: like 'start-work, where the future thunk’s work was previously stopped due to an internal stack overflow.
-   'sync: blocking (processes other than 0) or initiation of handing (process 0) for an “unsafe” operation in a future thunk’s evaluation; the operation must run in process 0.
-   'block: like 'sync, but for a part of evaluation that must be delayed until the future is [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29)ed, because the evaluation may depend on the current continuation.


# 11.4 Futures
-   'touch (never in process 0): like 'sync or 'block, but for a [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29) operation within a future thunk.
-   'overflow (never in process 0): like 'sync or 'block, but for the case that a process encountered an internal stack overflow while evaluating a future thunk.
-   'result or 'abort: waiting or handling for 'sync, 'block, or 'touch ended with a value or an error, respectively.
-   'suspend (never in process 0): a process blocked by 'sync, 'block, or 'touch abandoned evaluation of a future; some other process may pick up the future later.
-   'touch-pause and 'touch-resume (in process 0, only): waiting in [touch](#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29) for a future whose thunk is being evaluated in another process.
-   'missing: one or more events for the process were lost due to internal buffer limits before they could be reported, and the time-id field reports an upper limit on the time of the missing events; this kind of event is rare.
Assuming no 'missing events, then 'start-work, 'start-0-work, 'start-overflow-work is always paired with 'end-work; 'sync, 'block, and 'touch are always paired with 'result, 'abort, or 'suspend; and 'touch-pause is always paired with 'touch-resume.
In process 0, some event pairs can be nested within other event pairs: 'sync, 'block, or 'touch with 'result or 'abort; 'touch-pause with 'touch-resume; and 'start-work with 'end-work.


# 11.4 Futures
A 'block in process 0 is generated when an unsafe operation is handled. This type of event will contain a symbol in the unsafe-op-name field that is the name of the operation. In all other cases, this field contains #f.
The prim-name field will always be #f unless the event occurred on process 0 and its action is either 'block or 'sync. If these conditions are met, prim-name will contain the name of the Racket primitive which required the future to synchronize with the runtime thread (represented as a symbol).
The user-data field may take on a number of different values depending on both the action and prim-name fields:
-   'touch on process 0: contains the integer ID of the future being touched.
-   'sync and prim-name is '\|allocate memory\|: The size (in bytes) of the requested allocation.
-   'sync and prim-name is 'jit_on_demand: The runtime thread is performing a JIT compilation on behalf of the future future-id. The field contains the name of the function being JIT compiled (as a symbol).
-   'create: A new future was created. The field contains the integer ID of the newly created future.
------------------------------------------------------------------------


# 11.5 Places


### 11.5 Places
> > > <img src="finger.png" width="24" height="24" alt="+" />[Parallelism with Places](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=parallelism.html%23%2528part._effective-places%2529&version=8.18.0.13) in [The Racket Guide](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=index.html&version=8.18.0.13) introduces places.
|                                                                                |                                                                                |
|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------:|
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/place]())         |  package: [base](https://pkgs.racket-lang.org/package/base "Install this package using `raco pkg install base`") |
|  ([require](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._require%29%29) [racket/place/dynamic]()) |                                                                                |


# 11.5 Places
The bindings documented in this section are provided by the [racket/place](), [racket/place/dynamic](), and [racket](index.html) libraries, but not [racket/base](index.html).
[Places](#%28tech._place%29) enable the development of parallel programs that take advantage of machines with multiple processors, cores, or hardware threads.
> > > Currently, parallel support for places is enabled on all platforms that support Racket [CS](implementations.html#%28tech._c%29), the default implementation of Racket. The [3m](implementations.html#%28tech._3m%29) implementation also supports parallel execution of places by default on Windows, Linux x86/x86_64, and Mac OS x86/x86_64. To enable support for other platforms with [3m](implementations.html#%28tech._3m%29), use --enable-places with configure when building Racket. The [place-enabled?](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-enabled~3f%29%29) function reports whether places run in parallel.
> > >
> > > Implementation and operating-system constraints may limit the scalability of places. For example, although places can perform garbage collections in parallel in the [CS](implementations.html#%28tech._c%29) implementation or independently in the [3m](implementations.html#%28tech._3m%29) implementation, a garbage collection may need to manipulate a page table that is shared across all places, and that shared page table can be a bottleneck with enough places—perhaps around 8 or 16.


# 11.5 Places
A place is a parallel task that is effectively a separate instance of the Racket virtual machine, although all places run within a single operating-system process. Places communicate through place channels, which are endpoints for a two-way buffered communication.
To a first approximation, place channels support only immutable, transparent values as messages. In addition, place channels themselves can be sent across channels to establish new (possibly more direct) lines of communication in addition to any existing lines. Finally, mutable values produced by [shared-flvector](flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._shared-flvector%29%29), [make-shared-flvector](flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._make-shared-flvector%29%29), [shared-fxvector](fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._shared-fxvector%29%29), [make-shared-fxvector](fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._make-shared-fxvector%29%29), [shared-bytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._shared-bytes%29%29), and [make-shared-bytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._make-shared-bytes%29%29) can be sent across place channels; mutation of such values is visible to all places that share the value, because they are allowed in a shared memory space. See [place-message-allowed?](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29).


# 11.5 Places
A [place channel](#%28tech._place._channel%29) can be used as a [synchronizable event](sync.html#%28tech._synchronizable._event%29) (see [Events](sync.html)) to receive a value through the channel. A [place channel](#%28tech._place._channel%29) is [ready for synchronization](sync.html#%28tech._ready._for._synchronization%29) when a message is available on the channel, and the [place channel](#%28tech._place._channel%29)’s [synchronization result](sync.html#%28tech._synchronization._result%29) is the message (which is removed on synchronization). A place can also receive messages with [place-channel-get](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-get%29%29), and messages can be sent with [place-channel-put](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-channel-put%29%29).
Two [place channels](#%28tech._place._channel%29) are [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29) if they are endpoints for the same underlying channels while both or neither is a [place descriptor](#%28tech._place._descriptor%29). [Place channels](#%28tech._place._channel%29) can be [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29) without being [eq?](Equality.html#%28def._%28%28quote._~23~25kernel%29._eq~3f%29%29) after being sent messages through a [place channel](#%28tech._place._channel%29).


# 11.5 Places
Constraints on messages across a place channel—and therefore on the kinds of data that places share—enable greater parallelism than [future](futures.html#%28def._%28%28lib._racket%2Ffuture..rkt%29._future%29%29), even including separate [garbage collection](eval-model.html#%28tech._garbage._collection%29) of separate places. At the same time, the setup and communication costs for places can be higher than for [futures](futures.html#%28tech._future%29).
For example, the following expression launches two places, echoes a message to each, and then waits for the places to terminate:
> ```racket
> ( let ( [ pls ( for/list ( [ i ( in-range 2 ) ] )
> ( dynamic-place "place-worker.rkt" ' place-main ) ) ] )
> ( for ( [ i ( in-range 2 ) ]
> [ p pls ] )
> ( place-channel-put p i )
> ( printf "~a\n" ( place-channel-get p ) ) )
> ( for-each place-wait pls ) )
> ```
The "place-worker.rkt" module (in a file that is separate from the above code) must export the place-main function that each place executes, where place-main must accept a single [place channel](#%28tech._place._channel%29) argument:
> > "place-worker.rkt"
> >
> > > ```racket
> > > #lang racket
> > > ( provide place-main )
> > > ( define ( place-main pch )
> > > ( place-channel-put pch ( format "Hello from place ~a"
> > > ( place-channel-get pch ) ) ) )
> > > ```


# 11.5 Places
Place channels are subject to [garbage collection](eval-model.html#%28tech._garbage._collection%29), like other Racket values, and a [thread](eval-model.html#%28tech._thread%29) that is blocked reading from a [place channel](#%28tech._place._channel%29) can be garbage collected if [place channel](#%28tech._place._channel%29)’s writing end becomes unreachable. However, unlike normal [channel](channel.html#%28tech._channel%29) blocking, if otherwise unreachable threads are mutually blocked on place channels that are reachable only from the same threads, the threads and place channels are all considered reachable, instead of unreachable.
When a place is created, its [parameter](eval-model.html#%28tech._parameter%29) values are generally set to the initial values of the parameters in the creating place, except that the current values of the following parameters are used: [current-library-collection-paths](collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-paths%29%29), [current-library-collection-links](collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-links%29%29), and [current-compiled-file-roots](eval.html#%28def._%28%28quote._~23~25kernel%29._current-compiled-file-roots%29%29).
A newly created place is registered with the [current custodian](eval-model.html#%28tech._current._custodian%29), so that the place is terminated when the custodian is shut down.


#### 11.5.1 Using Places
> ```
(place-enabled?)  →  boolean?
```
Returns #t if Racket is configured so that dynamic-place and place create places that can run in parallel, #f if dynamic-place and place are simulated using thread.

> ```
(place? v)   →   boolean?
  v : any/c```

Returns #t if v is a place descriptor value, #f otherwise. Every [place descriptor](#%28tech._place._descriptor%29) is also a [place channel](#%28tech._place._channel%29).

> ```
(place-channel? v)  →  boolean?
  v : any/c
```
(parameter)	→
(-> or/c module-path? path?)```
Creates a [place](#%28tech._place%29) to run the procedure that is identified by module-path and start-name. The result is a [place descriptor](#%28tech._place._descriptor%29) value that represents the new parallel task; the place descriptor is returned immediately. The place descriptor value is also a [place channel](#%28tech._place._channel%29) that permits communication with the place.
The module indicated by module-path must export a function with the name start-name. The function must accept a single argument, which is a [place channel](#%28tech._place._channel%29) that corresponds to the other end of communication for the [place descriptor](#%28tech._place._descriptor%29) returned by [place](#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29).


# 11.5 Places
If location is provided, it must be a [place location](#%28tech._place._location%29), such as a distributed places node produced by [create-place-node](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=distributed-places&rel=index.html%23%2528def._%2528%2528lib._racket%252Fplace%252Fdistributed..rkt%2529._create-place-node%2529%2529&version=8.18.0.13).
When the [place](#%28tech._place%29) is created, the initial [exit handler](Exiting.html#%28tech._exit._handler%29) terminates the place, using the argument to the exit handler as the place’s completion value. Use ([exit](Exiting.html#%28def._%28%28quote._~23~25kernel%29._exit%29%29) v) to immediately terminate a place with the completion value v. Since a completion value is limited to an exact integer between 0 and 255, any other value for v is converted to 0.
If the function indicated by module-path and start-name returns, then the place terminates with the [completion value](#%28tech._completion._value%29) 0.


# 11.5 Places
In the created place, the [current-input-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-input-port%29%29) parameter is set to an empty input port, while the values of the [current-output-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-output-port%29%29) and [current-error-port](port-ops.html#%28def._%28%28quote._~23~25kernel%29._current-error-port%29%29) parameters are connected to the current ports in the creating place. If the output ports in the creating place are [file-stream ports](file-ports.html#%28tech._file._stream._port%29), then the connected ports in the created place share the underlying streams, otherwise a [thread](eval-model.html#%28tech._thread%29) in the creating place pumps bytes from the created place’s ports to the current ports in the creating place.
Most [parameters](eval-model.html#%28tech._parameter%29) in the created place have their original initial values, but the created place inherits the creating place’s values for the following parameters: [current-directory](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29), [current-library-collection-paths](collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-paths%29%29), [current-library-collection-links](collects.html#%28def._%28%28quote._~23~25kernel%29._current-library-collection-links%29%29), and [current-compiled-file-roots](eval.html#%28def._%28%28quote._~23~25kernel%29._current-compiled-file-roots%29%29).


# 11.5 Places
The module-path argument must not be a module path of the form ([quote](quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29) sym) unless the module is predefined (see [module-predefined?](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._module-predefined~3f%29%29)).
The [dynamic-place](#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29) binding is protected in the sense of [protect-out](require.html#%28form._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._protect-out%29%29), so access to this operation can be prevented by adjusting the code inspector (see [Code Inspectors](modprotect.html)).
Changed in version 8.2.0.7 of package base: Changed created place to inherit the creating place’s [current-directory](Filesystem.html#%28def._%28%28quote._~23~25kernel%29._current-directory%29%29) value.
> ```
(current-output-port)	→
(-> or/c output-port? #f)
```
(parameter)	→```

Returns the [completion value](#%28tech._completion._value%29) of the place indicated by p, blocking until the place has terminated.

If any pumping threads were created to connect a non-[file-stream port](file-ports.html#%28tech._file._stream._port%29) to the ports in the place for p (see [dynamic-place](#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29)), [place-wait](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-wait%29%29) returns only when the pumping threads have completed.

> ```
(place-dead-evt p)  →  evt?
  p : place?
```
(parameter)	→```


# 11.5 Places
Immediately terminates the place, setting the place’s [completion value](#%28tech._completion._value%29) to 1 if the place does not have a completion value already.
> ```
(parameter)	→
(-> or/c #f 'hang-up 'terminate)
```
Sends the main thread of place p a break; see Breaks.

> ```
(place-channel)    →    place-channel?   place-channel?```

Returns two [place channels](#%28tech._place._channel%29). Data sent through the first channel can be received through the second channel, and data sent through the second channel can be received from the first.

Typically, one place channel is used by the current [place](#%28tech._place%29) to send messages to a destination [place](#%28tech._place%29); the other place channel is sent to the destination [place](#%28tech._place%29) (via an existing [place channel](#%28tech._place._channel%29)).

> ```
(place-channel-put pch v)  →  void
  pch : place-channel?
  v : place-message-allowed?
```
Sends a message v on channel pch. Since place channels are asynchronous, place-channel-put calls are non-blocking.
See place-message-allowed? form information on automatic coercions in v, such as converting a mutable string to an immutable string.
> ```
(place-channel-get pch)   →   place-message-allowed?
  pch : place-channel?```
Returns a message received on channel pch, blocking until a message is available.
> ```
(place-channel-put/get pch v)  →  any/c
  pch : place-channel?
  v : any/c


# 11.5 Places
```

Sends an immutable message v on channel pch and then waits for a message (perhaps a reply) on the same channel.

> ```
(place-message-allowed? v)  →  boolean?
  v : any/c
```
Returns #t if v is allowed as a message on a place channel, #f otherwise.
If ([place-enabled?](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-enabled~3f%29%29)) returns #f, then the result is always #t and no conversions are performed on v as a message. Otherwise, the following kinds of data are allowed as messages:
-   [numbers](numbers.html#%28tech._number%29), [characters](characters.html#%28tech._character%29), [booleans](booleans.html#%28tech._boolean%29), [keywords](keywords.html#%28tech._keyword%29), and [#<void>](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=guide&rel=void_undefined.html&version=8.18.0.13);
-   [symbols](symbols.html#%28tech._symbol%29), where the [eq?](Equality.html#%28def._%28%28quote._~23~25kernel%29._eq~3f%29%29)ness of [uninterned](symbols.html#%28tech._uninterned%29) symbols is preserved within a single message, but not across messages;
-   [strings](strings.html#%28tech._string%29) and [byte strings](bytestrings.html#%28tech._byte._string%29), where mutable strings and byte strings are automatically replaced by immutable variants;
-   [paths](pathutils.html#%28tech._path%29) (for any platform);


# 11.5 Places
-   [pairs](pairs.html#%28tech._pair%29), [lists](pairs.html#%28tech._list%29), [box](boxes.html#%28tech._box%29)es, [vectors](vectors.html#%28tech._vector%29), and immutable [prefab](structures.html#%28tech._prefab%29) structures containing message-allowed values, where a mutable box is automatically replaced by an immutable box, a mutable vector is automatically replaced by an immutable vector and where [impersonators](chaperones.html#%28tech._impersonator%29) of boxes, vectors and [prefab](structures.html#%28tech._prefab%29) structures are copied;
-   [hash tables](hashtables.html#%28tech._hash._table%29) where mutable hash tables are automatically replaced by immutable variants, and where a hash table [impersonator](chaperones.html#%28tech._impersonator%29) is copied;
-   [place channels](#%28tech._place._channel%29), where a [place descriptor](#%28tech._place._descriptor%29) is automatically replaced by a plain place channel;
-   [file-stream ports](file-ports.html#%28tech._file._stream._port%29) and [TCP ports](tcp.html#%28tech._tcp._port%29), where the underlying representation (such as a file descriptor, socket, or handle) is duplicated in the sending place and attached to a fresh port in the receiving place;


# 11.5 Places
-   [C pointers](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=foreign&rel=Pointer_Types.html%23%2528tech._c._pointer%2529&version=8.18.0.13) as created or accessed via [ffi/unsafe](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=foreign&rel=index.html&version=8.18.0.13); and
-   values produced by [shared-flvector](flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._shared-flvector%29%29), [make-shared-flvector](flonums.html#%28def._%28%28lib._racket%2Fflonum..rkt%29._make-shared-flvector%29%29), [shared-fxvector](fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._shared-fxvector%29%29), [make-shared-fxvector](fixnums.html#%28def._%28%28lib._racket%2Ffixnum..rkt%29._make-shared-fxvector%29%29), [shared-bytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._shared-bytes%29%29), and [make-shared-bytes](bytestrings.html#%28def._%28%28quote._~23~25kernel%29._make-shared-bytes%29%29).
Changed in version 8.4.0.7 of package base: Include boxes in allowed messages.
> ```
value
prop:place-location : struct-type-property?
(place-location? v)  →  boolean?
  v : any/c


# 11.5 Places
```
A structure type property and associated predicate for implementations of place locations. The value of prop:place-location must be a procedure of four arguments: the place location itself, a module path, a symbol for the start function exported by the module, and a place name (which can be #f for an anonymous place).

A place location can be passed as the #:at argument to dynamic-place, which in turn simply calls the prop:place-location value of the place location.

A distributed places note created with create-place-node is an example of a place location.

#### 11.5.2 Syntactic Support for Using Places

The bindings in this section are not provided by [racket/place/dynamic]().

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>(place id body ...+)</p></blockquote></td></tr></tbody></table>

Creates a place that evaluates body expressions with id bound to a place channel. The bodys close only over id plus the top-level bindings of the enclosing module, because the bodys are lifted to a submodule. The result of place is a place descriptor, like the result of dynamic-place.

The generated submodule has the name place-body-n for an integer n, and the submodule exports a main function that takes a place channel for the new place. The submodule is not intended for use, however, except by the expansion of the place form.

The place binding is protected in the same way as dynamic-place.

> ```
syntax

(place* maybe-port ...
> id
> body ...+ )

maybe-port   =
    |   #:in in-expr
    |   #:out out-expr
    |   #:err err-expr```

Like [place](#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29), but supports optional #:in, #:out, and #:err expressions (at most one of each) to specify ports in the same way and with the same defaults as [dynamic-place*](#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29). The result of a [place*](#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2A%29%29) form is also the same as for [dynamic-place*](#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%2A%29%29).

The [place*](#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2A%29%29) binding is protected in the same way as [dynamic-place](#%28def._%28%28lib._racket%2Fplace..rkt%29._dynamic-place%29%29).

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>([place/context](#%28form._%28%28lib._racket%2Fplace..rkt%29._place%2Fcontext%29%29) id body ...+)</p></blockquote></td></tr></tbody></table>

Like [place](#%28form._%28%28lib._racket%2Fplace..rkt%29._place%29%29), but body [...](stx-patterns.html#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) may have free lexical variables, which are automatically sent to the newly-created place. Note that these variables must have values accepted by [place-message-allowed?](#%28def._%28%28lib._racket%2Fplace..rkt%29._place-message-allowed~3f%29%29), otherwise an [exn:fail:contract](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3acontract%29%29) exception is raised.

> ```
(processor-count)  →  exact-positive-integer?
```


# 11.5 Places
(current-logger)	→
(-> (any/c . → . void?) . → . any/c)```
Returns an engine object to encapsulate a thread that runs only when allowed. The proc procedure should accept one argument, and proc is run in the engine thread when [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29) is called. If [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29) returns due to a timeout, then the engine thread is suspended until a future call to [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29). Thus, proc only executes during the dynamic extent of a [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29) call.
The argument to proc is a procedure that takes a boolean, and it can be used to disable suspends (in case proc has critical regions where it should not be suspended). A true value passed to the procedure enables suspends, and #f disables suspends. Initially, suspends are allowed.
> ```
(engine? v)  →  any
  v : any/c


# 11.5 Places
```
Returns #t if v is an engine produced by engine, #f otherwise.

> ```
(engine-run until engine)   →   boolean?
  until : (or/c evt? real?)
  engine : engine?```

Allows the thread associated with engine to execute for up to as long as until milliseconds (if until is a real number) or until is ready (if until is an event). If engine’s procedure disables suspends, then the engine can run arbitrarily long until it re-enables suspends.

The [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29) procedure returns #t if engine’s procedure completes (or if it completed earlier), and the result is available via [engine-result](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-result%29%29). The [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29) procedure returns #f if engine’s procedure does not complete before it is suspended. If engine’s procedure raises an exception, then it is re-raised by [engine-run](#%28def._%28%28lib._racket%2Fengine..rkt%29._engine-run%29%29).

> ```
(engine-result engine)  →  any
  engine : engine?
```
(parameter)	→```
Forcibly terminates the thread associated with engine if it is still running, leaving the engine result unchanged.
------------------------------------------------------------------------


# 11.7 Machine Memory Order


### 11.7 Machine Memory Order
Unlike Racket [threads](eval-model.html#%28tech._thread%29), futures and places can expose the underlying machine’s memory model, including a weak memory ordering. For example, when a future writes to multiple slots in a mutable vector, it’s possible on some platforms for another future to observe the writes in a different order or not at all, unless the futures are explicitly synchronized. Similarly, shared byte strings or [fxvectors](fixnums.html#%28tech._fxvector%29) can expose the machine’s memory model across places.
Racket ensures that a machine’s memory model is not observed in a way that unsafely exposes the implementation of primitive datatypes. For example, it is not possible for one future to see a partially constructed primitive value as a result of reading a vector that is mutated by another future.


# 11.7 Machine Memory Order
The [box-cas!](boxes.html#%28def._%28%28quote._~23~25kernel%29._box-cas%21%29%29), [vector-cas!](vectors.html#%28def._%28%28quote._~23~25kernel%29._vector-cas%21%29%29), [unsafe-box*-cas!](unsafe.html#%28def._%28%28lib._racket%2Funsafe%2Fops..rkt%29._unsafe-box%2A-cas%21%29%29), [unsafe-vector*-cas!](unsafe.html#%28def._%28%28lib._racket%2Funsafe%2Fops..rkt%29._unsafe-vector%2A-cas%21%29%29), and [unsafe-struct*-cas!](unsafe.html#%28def._%28%28lib._racket%2Funsafe%2Fops..rkt%29._unsafe-struct%2A-cas%21%29%29) operations all provide a machine-level compare-and-set, so they can be used in ways that are specifically supported by the a machine’s memory model. The ([memory-order-acquire](#%28def._%28%28quote._~23~25kernel%29._memory-order-acquire%29%29)) and ([memory-order-release](#%28def._%28%28quote._~23~25kernel%29._memory-order-release%29%29)) operations similarly constrain machine-level stores and loads. Synchronization operations such as place messages, future [touch](futures.html#%28def._%28%28lib._racket%2Ffuture..rkt%29._touch%29%29)es, and [future semaphores](futures.html#%28tech._future._semaphore%29) imply suitable machine-level acquire and release ordering.
> ```
(memory-order-acquire)	→
(-> memory-order-release)


# 11.7 Machine Memory Order
```
(parameter)	→```

Finds the first pattern that matches the syntax object produced by stx-expr, and for which the corresponding fender-expr (if any) produces a true value; the result is from the corresponding result-expr, which is in tail position for the [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29) form. If no clause matches, then the [exn:fail:syntax](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29) exception is raised; the exception is generated by calling [raise-syntax-error](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._raise-syntax-error%29%29) with #f as the “name” argument, a string with a generic error message, and the result of stx-expr.

A syntax object matches a pattern as follows:

> > |     |
> > |-----|
> > | \_  |
>
> A [_](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29.__%29%29) pattern (i.e., an identifier with the same binding as [_](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29.__%29%29) and not among the literal-ids) matches any syntax object.

> > |     |
> > |-----|
> > | id  |
>
> An id matches any syntax object when it is not bound to [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) or [_](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29.__%29%29) and does not have the same binding as any literal-id. The id is further bound as pattern variable for the corresponding fender-expr (if any) and result-expr. A pattern-variable binding is a transformer binding; the pattern variable can be referenced only through forms like [syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%29%29). The binding’s value is the syntax object that matched the pattern with a depth marker of 0.
>
> With a stat-pattern, [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) is not treated specially. It either matches a literal-id or is bound as a pattern variable.
>
> An id that has the same binding as a literal-id matches a syntax object that is an identifier with the same binding in the sense of [free-identifier=?](stxcmp.html#%28def._%28%28quote._~23~25kernel%29._free-identifier~3d~3f%29%29). The match does not introduce any [pattern variables](#%28tech._pattern._variable%29).

> > |               |
> > |---------------|
> > | (pattern ...) |
>
> A (pattern ...) pattern matches a syntax object whose datum form (i.e., without lexical information) is a list with as many elements as sub-patterns in the pattern, and where each syntax object that corresponds to an element of the list matches the corresponding sub-pattern.
>
> Any [pattern variables](#%28tech._pattern._variable%29) bound by the sub-patterns are bound by the complete pattern; the bindings must all be distinct.

> > |                             |
> > |-----------------------------|
> > | (pattern ...+ . np-pattern) |
>
> Like the previous kind of pattern, but matches syntax objects that are not necessarily lists; for n sub-patterns before the final np-pattern, the syntax object’s datum must be a pair such that n-1 [cdr](pairs.html#%28def._%28%28quote._~23~25kernel%29._cdr%29%29)s produce pairs. The final np-pattern is matched against the syntax object corresponding to the nth [cdr](pairs.html#%28def._%28%28quote._~23~25kernel%29._cdr%29%29) (or the [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) coercion of the datum using the nearest enclosing syntax object’s lexical context and source location).

> > |                                            |
> > |--------------------------------------------|
> > | (pattern ... pattern ellipsis pattern ...) |
>
> Like the (pattern ...) kind of pattern, but matching a syntax object with any number (zero or more) elements that match the sub-pattern followed by ellipsis in the corresponding position relative to other sub-patterns.
>
> For each pattern variable bound by the sub-pattern followed by ellipsis, the larger pattern binds the same pattern variable to a list of values, one for each element of the syntax object matched to the sub-pattern, with an incremented [depth marker](#%28tech._depth._marker%29). (The sub-pattern itself may contain ellipsis, leading to a pattern variables bound to lists of lists of syntax objects with a [depth marker](#%28tech._depth._marker%29) of 2, and so on.)
>
> All patterns forms with ellipsis apply only when ellipsis is not among the literal-ids.

> > |                                                         |
> > |---------------------------------------------------------|
> > | (pattern ... pattern ellipsis pattern ... . np-pattern) |
>
> Like the previous kind of pattern, but with a final np-pattern as for (pattern [...+](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=syntax&rel=stxparse-patterns.html%23%2528form._%2528%2528lib._syntax%252Fparse..rkt%2529._......%252B%2529%2529&version=8.18.0.13) . np-pattern). The final np-pattern never matches a syntax object whose datum is a pair.

> > |                |
> > |----------------|
> > | #(pattern ...) |
>
> Like a (pattern ...) pattern, but matching a vector syntax object whose elements match the corresponding sub-patterns.

> > |                                             |
> > |---------------------------------------------|
> > | #(pattern ... pattern ellipsis pattern ...) |
>
> Like a (pattern [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) pattern ellipsis pattern [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) pattern, but matching a vector syntax object whose elements match the corresponding sub-patterns.

> > |           |
> > |-----------|
> > | #&pattern |
>
> Matches a box syntax object whose content matches the pattern.

> > |                           |
> > |---------------------------|
> > | #s(key-datum pattern ...) |
>
> Like a (pattern ...) pattern, but matching a [prefab](structures.html#%28tech._prefab%29) structure syntax object whose fields match the corresponding sub-patterns. The key-datum must correspond to a valid first argument to [make-prefab-struct](structutils.html#%28def._%28%28quote._~23~25kernel%29._make-prefab-struct%29%29).

> > |                                                        |
> > |--------------------------------------------------------|
> > | #s(key-datum pattern ... pattern ellipsis pattern ...) |
>
> Like a (pattern ... pattern ellipsis pattern ...) pattern, but matching a [prefab](structures.html#%28tech._prefab%29) structure syntax object whose elements match the corresponding sub-patterns.

> > |                         |
> > |-------------------------|
> > | (ellipsis stat-pattern) |
>
> Matches the same as stat-pattern, which is like a pattern, but identifiers with the binding [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) are treated the same as other ids.

> > |       |
> > |-------|
> > | const |
>
> A const is any datum that does not match one of the preceding forms; a syntax object matches a const pattern when its datum is [equal?](Equality.html#%28def._%28%28quote._~23~25kernel%29._equal~3f%29%29) to the [quote](quote.html#%28form._%28%28quote._~23~25kernel%29._quote%29%29)d const.

If stx-expr produces a non-[syntax object](syntax-model.html#%28tech._syntax._object%29), then its result is converted to a syntax object using [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) and the lexical context and source location of the stx-expr.

If stx-expr produces a syntax object that is [tainted](stxcerts.html#%28tech._tainted%29), then any syntax object bound by a pattern are [tainted](stxcerts.html#%28tech._tainted%29).

Examples:

> ```racket
> > ( require ( for-syntax racket/base ) )
> > ( define-syntax ( swap stx ) ( syntax-case stx ( ) [ ( _ a b ) #' ( let ( [ t a ] ) ( set! a b ) ( set! b t ) ) ] ) )
> > ( let ( [ x 5 ] [ y 10 ] ) ( swap x y ) ( list x y ) )
> '(10 5)
> > ( syntax-case #' ( ops 1 2 3 => + ) ( => ) [ ( _ x ... => op ) #' ( op x ... ) ] )
> #<syntax:eval:686:0 (+ 1 2 3)>
> > ( syntax-case #' ( let ( [ x 5 ] [ y 9 ] [ z 12 ] ) ( + x y z ) ) ( let ) [ ( let ( [ var expr ] ... ) body ... ) ( list #' ( var ... ) #' ( expr ... ) ) ] )
> '(#<syntax:eval:687:0 (x y z)> #<syntax:eval:687:0 (5 9 12)>)
> ```

> ```
syntax

(syntax-case* stx-expr (literal-id ...) id-compare-expr
> clause ... )
```


# 11.7 Machine Memory Order
Like syntax-case, but id-compare-expr must produce a procedure that accepts two arguments. A literal-id in a pattern matches an identifier for which the procedure returns true when given the identifier to match (as the first argument) and the identifier in the pattern (as the second argument).
In other words, syntax-case is like syntax-case* with an id-compare-expr that produces free-identifier=?.
> ```
syntax
(with-syntax ([pattern stx-expr] ...)
> body ...+ )```
Similar to [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29), in that it matches a pattern to a syntax object. Unlike [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29), all patterns are matched, each to the result of a corresponding stx-expr, and the pattern variables from all matches (which must be distinct) are bound with a single body sequence. The result of the [with-syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._with-syntax%29%29) form is the result of the last body, which is in tail position with respect to the [with-syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._with-syntax%29%29) form.
If any pattern fails to match the corresponding stx-expr, the [exn:fail:syntax](exns.html#%28def._%28%28lib._racket%2Fprivate%2Fbase..rkt%29._exn~3afail~3asyntax%29%29) exception is raised.


# 11.7 Machine Memory Order
A [with-syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._with-syntax%29%29) form is roughly equivalent to the following [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29) form:
> ```racket
> ( syntax-case ( list stx-expr ... ) ( )
> [ ( pattern ... ) ( let ( ) body ...+ ) ] )
> ```
However, if any individual stx-expr produces a non-[syntax object](syntax-model.html#%28tech._syntax._object%29), then it is converted to one using [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) and the lexical context and source location of the individual stx-expr.
Examples:
> ```racket
> > ( define-syntax ( hello stx ) ( syntax-case stx ( ) [ ( _ name place ) ( with-syntax ( [ print-name #' ( printf "~a\n" ' name ) ] [ print-place #' ( printf "~a\n" ' place ) ] ) #' ( begin ( define ( name times ) ( printf "Hello\n" ) ( for ( [ i ( in-range 0 times ) ] ) print-name ) ) ( define ( place times ) ( printf "From\n" ) ( for ( [ i ( in-range 0 times ) ] ) print-place ) ) ) ) ] ) )
> > ( hello jon utah )
> > ( jon 2 )
> Hello jon jon
> > ( utah 2 )
> From utah utah
> > ( define-syntax ( math stx ) ( define ( make+1 expression ) ( with-syntax ( [ e expression ] ) #' ( + e 1 ) ) ) ( syntax-case stx ( ) [ ( _ numbers ... ) ( with-syntax ( [ ( added ... ) ( map make+1 ( syntax->list #' ( numbers ... ) ) ) ] ) #' ( begin ( printf "got ~a\n" added ) ... ) ) ] ) )
> > ( math 3 1 4 1 5 9 )
> got 4 got 2 got 5 got 2 got 6 got 10
> ```


# 11.7 Machine Memory Order
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%29%29) template)

template	 	=	 	id

 	 	|	 	(head-template ...)

 	 	|	 	(head-template ...+ . template)

 	 	|	 	#(head-template ...)

 	 	|	 	#&template

 	 	|	 	#s(key-datum head-template ...)

 	 	|	 	([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) template template)

 	 	|	 	(ellipsis stat-template)

 	 	|	 	const

head-template	 	=	 	template

 	 	|	 	head-template ellipsis ...+

 	 	|	 	([~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29) . template)

 	 	|	 	([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) head-template head-template)

 	 	|	 	([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) head-template)

stat-template	 	=	 	like template, but without [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29), [~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29), and [~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29)

ellipsis	 	=	 	[...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)


# 11.7 Machine Memory Order
Constructs a syntax object based on a template, which can include [pattern variables](#%28tech._pattern._variable%29) bound by [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29) or [with-syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._with-syntax%29%29).
A template produces a single syntax object. A head-template produces a sequence of zero or more syntax objects. A stat-template is like a template, except that [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29), [~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29), and [~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29) are interpreted as constants instead of template forms.
A template produces a syntax object as follows:


# 11.7 Machine Memory Order
> > |     |
> > |-----|
> > | id  |
>
> If id is bound as a [pattern variable](#%28tech._pattern._variable%29), then id as a template produces the [pattern variable](#%28tech._pattern._variable%29)’s match result. Unless the id is a sub-template that is replicated by ellipsis in a larger template, the [pattern variable](#%28tech._pattern._variable%29)’s value must be a syntax object with a [depth marker](#%28tech._depth._marker%29) of 0 (as opposed to a list of matches).
>
> More generally, if the [pattern variable](#%28tech._pattern._variable%29)’s value has a depth marker n, then it can only appear within a template where it is replicated by at least n ellipsises. In that case, the template will be replicated enough times to use each match result at least once.
>
> If id is not bound as a pattern variable, then id as a template produces ([quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29) id).
> > |                     |
> > |---------------------|
> > | (head-template ...) |
>
> Produces a syntax object whose datum is a list, and where the elements of the list correspond to syntax objects produced by the head-templates.
> > |                                |
> > |--------------------------------|
> > | (head-template ... . template) |
>
> Like the previous form, but the result is not necessarily a list; instead, the place of the empty list in the resulting syntax object’s datum is taken by the syntax object produced by template.


# 11.7 Machine Memory Order
> > |                      |
> > |----------------------|
> > | #(head-template ...) |
>
> Like the (head-template [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) form, but producing a syntax object whose datum is a vector instead of a list.
> > |            |
> > |------------|
> > | #&template |
>
> Produces a syntax object whose datum is a box holding the syntax object produced by template.
> > |                                 |
> > |---------------------------------|
> > | #s(key-datum head-template ...) |
>
> Like the (head-template [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)) form, but producing a syntax object whose datum is a [prefab](structures.html#%28tech._prefab%29) structure instead of a list. The key-datum must correspond to a valid first argument of [make-prefab-struct](structutils.html#%28def._%28%28quote._~23~25kernel%29._make-prefab-struct%29%29).


# 11.7 Machine Memory Order
> > |                                                                                |
> > |----------------------------------------------------------------------------------------------------------------------------------------|
> > | ([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) template1 template2) |
>
> Produces the result of template1 if template1 has no pattern variables with “missing values”; otherwise, produces the result of template2.
>
> A pattern variable bound by [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29) never has a missing value, but pattern variables bound by [syntax-parse](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=syntax&rel=Parsing_Syntax.html%23%2528form._%2528%2528lib._syntax%252Fparse..rkt%2529._syntax-parse%2529%2529&version=8.18.0.13) (for example, [~or](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=syntax&rel=stxparse-patterns.html%23%2528form._%2528%2528lib._syntax%252Fparse..rkt%2529._%7E7eor%2529%2529&version=8.18.0.13) or [~optional](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=syntax&rel=stxparse-patterns.html%23%2528form._%2528%2528lib._syntax%252Fparse..rkt%2529._%7E7eoptional%2529%2529&version=8.18.0.13) patterns) can.
>
>
>
> Examples:
>
>
>
>


# 11.7 Machine Memory Order
>
> > ```racket
> > > ( syntax-parse #' ( m 1 2 3 ) [ ( _ ( ~optional ( ~seq #:op op:expr ) ) arg:expr ... ) #' ( ( ~? op + ) arg ... ) ] )
> > #<syntax:eval:3:0 (+ 1 2 3)>
> > > ( syntax-parse #' ( m #:op max 1 2 3 ) [ ( _ ( ~optional ( ~seq #:op op:expr ) ) arg:expr ... ) #' ( ( ~? op + ) arg ... ) ] )
> > #<syntax:eval:4:0 (max 1 2 3)>
> > ```
>
>
> > |                          |
> > |--------------------------|
> > | (ellipsis stat-template) |
>
> Produces the same result as stat-template, which is like a template, but [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29), [~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29), and [~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29) are treated like an id (with no pattern binding).
> > |       |
> > |-------|
> > | const |
>
> A const template is any form that does not match the preceding cases, and it produces the result ([quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29) const).
A head-template produces a sequence of syntax objects; that sequence is “inlined” into the result of the enclosing template. The result of a head-template is defined as follows:
> > |          |
> > |----------|
> > | template |
>
> Produces one syntax object, according to the rules for template above.


# 11.7 Machine Memory Order
> > |                             |
> > |-----------------------------|
> > | head-template ellipsis ...+ |
>
> Generates a sequence of syntax objects by “[map](pairs.html#%28def._%28%28lib._racket%2Fprivate%2Fmap..rkt%29._map%29%29)ping” the head-template over the values of its pattern variables. The number of iterations depends on the values of the [pattern variables](#%28tech._pattern._variable%29) referenced within the sub-template.
>
> To be more precise: Let outer be inner followed by one ellipsis. A [pattern variable](#%28tech._pattern._variable%29) is an iteration pattern variable for outer if occurs at a depth equal to its [depth marker](#%28tech._depth._marker%29). There must be at least one; otherwise, an error is raised. If there are multiple iteration variables, then all of their values must be lists of the same length. The result for outer is produced by [map](pairs.html#%28def._%28%28lib._racket%2Fprivate%2Fmap..rkt%29._map%29%29)ping the inner template over the [iteration pattern variable](#%28tech._iteration._pattern._variable%29) values and decreasing their effective [depth markers](#%28tech._depth._marker%29) by 1 within inner. The outer result is formed by appending the inner results.
>
> Consequently, if a [pattern variable](#%28tech._pattern._variable%29) occurs at a depth greater than its [depth marker](#%28tech._depth._marker%29), it is used as an [iteration pattern variable](#%28tech._iteration._pattern._variable%29) for the innermost ellipses but not the outermost. A [pattern variable](#%28tech._pattern._variable%29) must not occur at a depth less than its [depth marker](#%28tech._depth._marker%29); otherwise, an error is raised.


# 11.7 Machine Memory Order
>
>
> >
<colgroup><col style="width: 100%" /></colgroup>

syntax

([~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29) . template)

>
>
>
>
>
> Produces the sequence of elements in the syntax list produced by template. If template does not produce a proper syntax list, an exception is raised.
>
>
>
>
>
> Examples:
>
>
>
>
>
> > ```racket
> > > ( with-syntax ( [ ( key ... ) #' ( ' a ' b ' c ) ] [ ( val ... ) #' ( 1 2 3 ) ] ) #' ( hash ( ~@ key val ) ... ) )
> > #<syntax:eval:2:0 (hash (quote a) 1 (quote b) 2 (quote c) 3)>
> > > ( with-syntax ( [ xs #' ( 2 3 4 ) ] ) #' ( list 1 ( ~@ . xs ) 5 ) )
> > #<syntax:eval:3:0 (list 1 2 3 4 5)>
> > ```
>
>
>
>
> >
<colgroup><col style="width: 100%" /></colgroup>

syntax

([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) head-template1 head-template2)

>
>
>
>
>
> Produces the result of head-template1 if none of its pattern variables have “missing values”; otherwise produces the result of head-template2.
>
>


# 11.7 Machine Memory Order
> > |                                                                                |
> > |----------------------------------------------------------------------------------------------------------------------------------|
> > | ([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) head-template) |
>
> Produces the result of head-template if none of its pattern variables have “missing values”; otherwise produces nothing.
>
> Equivalent to ([~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) head-template ([~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29))).
A (syntax template) form is normally abbreviated as #'template; see also [Reading Quotes](reader.html#%28part._parse-quote%29). If template contains no pattern variables, then #'template is equivalent to ([quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29) template).
Changed in version 6.90.0.25 of package base: Added [~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29) and [~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29) template)


# 11.7 Machine Memory Order
Like [syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%29%29), but ([unsyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax%29%29) expr) and ([unsyntax-splicing](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax-splicing%29%29) expr) escape to an expression within the template.
The expr must produce a syntax object (or syntax list) to be substituted in place of the [unsyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax%29%29) or [unsyntax-splicing](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax-splicing%29%29) form within the quasiquoting template, just like [unquote](quasiquote.html#%28form._%28%28quote._~23~25kernel%29._unquote%29%29) and [unquote-splicing](quasiquote.html#%28form._%28%28quote._~23~25kernel%29._unquote-splicing%29%29) within [quasiquote](quasiquote.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._quasiquote%29%29), except that a hash table value position is not an escape position for [quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29). (If the escaped expression does not generate a syntax object, it is converted to one in the same way as for the right-hand side of [with-syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._with-syntax%29%29).) Nested [quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29)es introduce quasiquoting layers in the same way as nested [quasiquote](quasiquote.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._quasiquote%29%29)s.


# 11.7 Machine Memory Order
Also analogous to [quasiquote](quasiquote.html#%28form._%28%28lib._racket%2Fprivate%2Fletstx-scheme..rkt%29._quasiquote%29%29), the reader converts #\` to [quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29), #, to [unsyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax%29%29), and #,@ to [unsyntax-splicing](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax-splicing%29%29). See also [Reading Quotes](reader.html#%28part._parse-quote%29).
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([unsyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax%29%29) [expr](https://plt.cs.northwestern.edu/new-snapshots/new-snapshots/doc/local-redirect/index.html?doc=syntax&rel=Library_Syntax_Classes_and_Literal_Sets.html%23%2528form._%2528%2528lib._syntax%252Fparse..rkt%2529._expr%2529%2529&version=8.18.0.13))

Illegal as an expression form. The [unsyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax%29%29) form is for use only with a [quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29) template.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([unsyntax-splicing](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax-splicing%29%29) expr)


# 11.7 Machine Memory Order
Illegal as an expression form. The [unsyntax-splicing](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._unsyntax-splicing%29%29) form is for use only with a [quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29) template.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax

([syntax/loc](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%2Floc%29%29) loc-expr template)

<colgroup><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /></colgroup>

  	loc-expr	 	:
( or/c #f srcloc? syntax?
> ( list/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) )
> ( vector/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) ) )

Like [syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%29%29), except that the immediate resulting syntax object takes its source-location information from the result of loc-expr.


# 11.7 Machine Memory Order
Only the source location of the immediate result—the “outermost” syntax object—is adjusted. The source location is not adjusted if both the source and position of loc-expr are #f. The source location is adjusted only if the resulting syntax object comes from the template itself rather than the value of a syntax pattern variable. For example, if x is a syntax pattern variable, then ([syntax/loc](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%2Floc%29%29) loc-expr x) does not use the location of loc-expr.
Changed in version 6.90.0.25 of package base: Previously, [syntax/loc](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%2Floc%29%29) did not enforce the contract on loc-expr if template was just a pattern variable.
Changed in version 8.2.0.6: Allows loc-expr to be any source location value that [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) accepts.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax


# 11.7 Machine Memory Order

([quasisyntax/loc](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%2Floc%29%29) loc-expr template)

<colgroup><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /><col style="width: 16%" /></colgroup>

  	loc-expr	 	:
( or/c #f srcloc? syntax?
> ( list/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) )
> ( vector/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) ) )

Like [quasisyntax](#%28form._%28%28lib._racket%2Fprivate%2Fqqstx..rkt%29._quasisyntax%29%29), but with source-location assignment like [syntax/loc](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%2Floc%29%29).
Changed in version 8.2.0.6 of package base: Allows loc-expr to be any source location value that [datum->syntax](stxops.html#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) accepts.
>
<colgroup><col style="width: 100%" /></colgroup>

syntax


# 11.7 Machine Memory Order

([quote-syntax/prune](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._quote-syntax%2Fprune%29%29) id)

Like [quote-syntax](Syntax_Quoting__quote-syntax.html#%28form._%28%28quote._~23~25kernel%29._quote-syntax%29%29), but the lexical context of id is pruned via [identifier-prune-lexical-context](stxops.html#%28def._%28%28quote._~23~25kernel%29._identifier-prune-lexical-context%29%29) to including binding only for the symbolic name of id and for '#%top. Use this form to quote an identifier when its lexical information will not be transferred to other syntax objects (except maybe to '#%top for a top-level binding).
> ```
syntax
(syntax-rules (literal-id ...)
> [ ( id . pattern ) template ] ... )


# 11.7 Machine Memory Order
```
Equivalent to

> ```racket
> ( lambda ( stx )
> ( syntax-case stx ( literal-id ... )
> [ ( generated-id . pattern ) ( syntax-protect #' template ) ] ... ) )
> ```

where each generated-id binds no identifier in the corresponding template. This in particular means that the id positions are ignored. Conventionally, the id positions should be the identifier _.

Examples:

> ```racket
> > ( define-syntax my-let* ( syntax-rules ( ) [ ( _ ( ) body ... ) ( let ( ) body ... ) ] [ ( _ ( [ x v ] binding ... ) body ... ) ( let ( [ x v ] ) ( my-let* ( binding ... ) body ... ) ) ] ) )
> > ( my-let* ( [ x 42 ] [ x ( + x 1 ) ] ) x )
> 43
> ```

> ```
syntax

(syntax-id-rules (literal-id ...)
> [ pattern template ] ... )```

Equivalent to

> ```racket
> ( make-set!-transformer
> ( lambda ( stx )
> ( syntax-case stx ( literal-id ... )
> [ pattern ( syntax-protect #' template ) ] ... ) ) )
> ```

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>([define-syntax-rule](#%28form._%28%28lib._racket%2Fprivate%2Fmisc..rkt%29._define-syntax-rule%29%29) (id . pattern) template)</p></blockquote></td></tr></tbody></table>

Equivalent to

> ```racket
> ( define-syntax id
> ( syntax-rules ( )
> [ ( id . pattern ) template ] ) )
> ```

but with syntax errors potentially phrased in terms of pattern.

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>[...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29)</p></blockquote></td></tr></tbody></table>

The [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) transformer binding prohibits [...](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._......%29%29) from being used as an expression. This binding is useful only in syntax patterns and templates (or other unrelated expression forms that treat it specially like [->](function-contracts.html#%28form._%28%28lib._racket%2Fcontract%2Fbase..rkt%29._-~3e%29%29)), where it indicates repetitions of a pattern or template. See [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29) and [syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%29%29).

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>[_](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29.__%29%29)</p></blockquote></td></tr></tbody></table>

The [_](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29.__%29%29) transformer binding prohibits [_](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29.__%29%29) from being used as an expression. This binding is useful only in syntax patterns, where it indicates a pattern that matches any syntax object. See [syntax-case](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax-case%29%29).

> <table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>[~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29)</p></blockquote></td></tr></tbody></table></td></tr><tr><td><table data-cellpadding="0" data-cellspacing="0"><colgroup><col style="width: 100%" /></colgroup><tbody><tr><td><blockquote>

<p>syntax</p>

<p>[~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29)</p></blockquote></td></tr></tbody></table></td></tr></tbody></table>

The [~?](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~3f%29%29) and [~@](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._~7e~40%29%29) transformer bindings prohibit these forms from being used as an expression. The bindings are useful only in syntax templates. See [syntax](#%28form._%28%28lib._racket%2Fprivate%2Fstxcase-scheme..rkt%29._syntax%29%29).

Added in version 6.90.0.25 of package base.

> ```
(syntax-pattern-variable? v)  →  boolean?
  v : any/c
```


# 11.7 Machine Memory Order
Returns #t if v is a value that, as a transformer-binding value, makes the bound variable as pattern variable in syntax and other forms. To check whether an identifier is a pattern variable, use syntax-local-value to get the identifier’s transformer value, and then test the value with syntax-pattern-variable?.
The syntax-pattern-variable? procedure is provided for-syntax by racket/base.
------------------------------------------------------------------------


# 12.2 Syntax Object Content


### 12.2 Syntax Object Content
> ```
(syntax? v)   →   boolean?
  v : any/c```
Returns #t if v is a [syntax object](syntax-model.html#%28tech._syntax._object%29), #f otherwise. See also [Syntax Objects](syntax-model.html#%28part._stxobj-model%29).
Examples:
> ```racket
> > ( syntax? #' quinoa )
> #t
> > ( syntax? #' ( spelt triticale buckwheat ) )
> #t
> > ( syntax? ( datum->syntax #f ' millet ) )
> #t
> > ( syntax? "barley" )
> #f
> ```
> ```
(identifier? v)  →  boolean?
  v : any/c
```
Returns #t if v is a syntax object and (syntax-e stx) produces a symbol.

Examples:

> ```racket
> > ( identifier? #' linguine )
> #t
> > ( identifier? #' ( if wheat? udon soba ) )
> #f
> > ( identifier? ' ramen )
> #f
> > ( identifier? 15 )
> #f
> ```

> ```
(syntax-source stx)   →   any/c
  stx : syntax?```

Returns the source component of the [source location](exns.html#%28tech._source._location%29) for the [syntax object](syntax-model.html#%28tech._syntax._object%29) stx, or #f if none is known. The source is represented by an arbitrary value (e.g., one passed to [read-syntax](Reading.html#%28def._%28%28quote._~23~25kernel%29._read-syntax%29%29)), but it is typically a file path string.

See also [syntax-srcloc](#%28def._%28%28lib._racket%2Fsyntax-srcloc..rkt%29._syntax-srcloc%29%29) from [racket/syntax-srcloc](#%28mod-path._racket%2Fsyntax-srcloc%29).

> ```
(syntax-line stx)  →  (or/c exact-positive-integer? #f)
  stx : syntax?
```


# 12.2 Syntax Object Content
Returns the line number (positive exact integer) of the source location for the start of the syntax object in its source, or #f if the line number or source is unknown. See also Counting Positions, Lines, and Columns.
Changed in version 7.0 of package base: Dropped a guarantee that syntax-line and syntax-column both produce #f or both produce integers.
> ```
(syntax-column stx)   →   (or/c exact-nonnegative-integer? #f)
  stx : syntax?```
Returns the column number (non-negative exact integer) of the [source location](exns.html#%28tech._source._location%29) for the start of the [syntax object](syntax-model.html#%28tech._syntax._object%29) in its source, or #f if the source column is unknown. See also [Counting Positions, Lines, and Columns](linecol.html).
Changed in version 7.0 of package base: Dropped a guarantee that [syntax-line](#%28def._%28%28quote._~23~25kernel%29._syntax-line%29%29) and [syntax-column](#%28def._%28%28quote._~23~25kernel%29._syntax-column%29%29) both produce #f or both produce integers.
> ```
(syntax-position stx)  →  (or/c exact-positive-integer? #f)
  stx : syntax?


# 12.2 Syntax Object Content
```
Returns the position (positive exact integer) of the source location for the start of the syntax object in its source, or #f if the source position is unknown. The position is intended to be a character position, but reading from a port without line counting enabled will produce a position as a byte offset. See also Counting Positions, Lines, and Columns.

> ```
(syntax-span stx)   →   (or/c exact-nonnegative-integer? #f)
  stx : syntax?```

Returns the span (non-negative exact integer) of the [source location](exns.html#%28tech._source._location%29) for [syntax object](syntax-model.html#%28tech._syntax._object%29) in its source, or #f if the span is unknown. The span is intended to count in characters, but reading from a port without line counting enabled will produce a span in bytes. See also [Counting Positions, Lines, and Columns](linecol.html).

> ```
(syntax-original? stx)  →  boolean?
  stx : syntax?
```
(hidden)	→
(-> or/c module-path-index? symbol? path? resolved-module-path? #f)```


# 12.2 Syntax Object Content
Returns an indication of the module whose source contains stx, or #f if no source module for stx can be inferred from its lexical context. If source? is #f, then result is a module path index or symbol (see [Compiled Modules and References](Module_Names_and_Loading.html#%28part._modpathidx%29)) or a [resolved module path](Module_Names_and_Loading.html#%28tech._resolved._module._path%29); if source? is true, the result is a path or symbol corresponding to the loaded module’s source in the sense of [current-module-declare-source](Module_Names_and_Loading.html#%28def._%28%28quote._~23~25kernel%29._current-module-declare-source%29%29).
Note that [syntax-source-module](#%28def._%28%28quote._~23~25kernel%29._syntax-source-module%29%29) does not consult the source location of stx. The result is based on the [lexical information](syntax-model.html#%28tech._lexical._information%29) of stx.
> ```
(syntax-e stx)  →  any/c
  stx : syntax?


# 12.2 Syntax Object Content
```
Unwraps the immediate datum structure from a syntax object, leaving nested syntax structure (if any) in place. The result of (syntax-e stx) is one of the following:

-  a symbol

-  a syntax pair (described below)

-  the empty list

-  an immutable vector containing syntax objects

-  an immutable box containing syntax objects

-  an immutable hash table containing syntax object values (but not necessarily syntax object keys)

-  an immutable prefab structure containing syntax objects

-  some other kind of datum—usually a number, boolean, or string—that is interned when datum-intern-literal would convert the value

Examples:

> ```racket
> > ( syntax-e #' a )
> 'a
> > ( syntax-e #' ( x . y ) )
> '(#<syntax:eval:11:0 x> . #<syntax:eval:11:0 y>)
> > ( syntax-e #' # ( 1 2 ( + 3 4 ) ) )
> '#(#<syntax:eval:12:0 1> #<syntax:eval:12:0 2> #<syntax:eval:12:0 (+ 3 4)>)
> > ( syntax-e #' #& "hello world" )
> '#&#<syntax:eval:13:0 "hello world">
> > ( syntax-e #' #hash ( ( imperial . "yellow" ) ( festival . "green" ) ) )
> '#hash((festival . #<syntax:eval:14:0 "green">) (imperial . #<syntax:eval:14:0 "yellow">))
> > ( syntax-e #' # ( point 3 4 ) )
> '#(#<syntax:eval:15:0 point> #<syntax:eval:15:0 3> #<syntax:eval:15:0 4>)
> > ( syntax-e #' 3 )
> 3
> > ( syntax-e #' "three" )
> "three"
> > ( syntax-e #' #t )
> #t
> ```

A syntax pair is a pair containing a syntax object as its first element, and either the empty list, a syntax pair, or a syntax object as its second element.

A syntax object that is the result of read-syntax reflects the use of delimited . in the input by creating a syntax object for every pair of parentheses in the source, and by creating a pair-valued syntax object only for parentheses in the source. See Reading Pairs and Lists for more information.

If stx is tainted, then any syntax object in the result of (syntax-e stx) is tainted. The results from multiple calls to syntax-e of stx are eq?.

> ```
(syntax  →  list stx)   →   (or/c list? #f)
  stx : syntax?```

Returns a list of [syntax object](syntax-model.html#%28tech._syntax._object%29)s or #f. The result is a list of [syntax object](syntax-model.html#%28tech._syntax._object%29)s when ([syntax->datum](#%28def._%28%28quote._~23~25kernel%29._syntax-~3edatum%29%29) stx) would produce a list. In other words, [syntax pairs](#%28tech._syntax._pair%29) in ([syntax-e](#%28def._%28%28quote._~23~25kernel%29._syntax-e%29%29) stx) are flattened.

If stx is [tainted](stxcerts.html#%28tech._tainted%29), then any syntax object in the result of ([syntax->list](#%28def._%28%28quote._~23~25kernel%29._syntax-~3elist%29%29) stx) is [tainted](stxcerts.html#%28tech._tainted%29).

Examples:

> ```racket
> > ( syntax->list #' ( ) )
> '()
> > ( syntax->list #' ( 1 ( + 3 4 ) 5 6 ) )
> '(#<syntax:eval:20:0 1> #<syntax:eval:20:0 (+ 3 4)> #<syntax:eval:20:0 5> #<syntax:eval:20:0 6>)
> > ( syntax->list #' a )
> #f
> ```

> ```
(syntax  →  datum stx)  →  any/c
  stx : syntax?
```


# 12.2 Syntax Object Content
Returns a datum by stripping the lexical information, source-location information, properties, and tamper status from stx. Inside of pairs, (immutable) vectors, (immutable) boxes, immutable hash table values (not keys), and immutable prefab structures, syntax objects are recursively stripped.
The stripping operation does not mutate stx; it creates new pairs, vectors, boxes, hash tables, and prefab structures as needed to strip lexical and source-location information recursively.
Examples:
> ```racket
> > ( syntax  →  datum #' a )
> 'a
> > ( syntax  →  datum #' ( x . y ) )
> '(x . y)
> > ( syntax  →  datum #' # ( 1 2 ( + 3 4 ) ) )
> '#(1 2 (+ 3 4))
> > ( syntax  →  datum #' #& "hello world" )
> '#&"hello world"
> > ( syntax  →  datum #' #hash ( ( imperial . "yellow" ) ( festival . "green" ) ) )
> '#hash((festival . "green") (imperial . "yellow"))
> > ( syntax  →  datum #' # ( point 3 4 ) )
> '#(point 3 4)
> > ( syntax  →  datum #' 3 )
> 3
> > ( syntax  →  datum #' "three" )
> "three"
> > ( syntax  →  datum #' #t )
> #t
> ```
> ```
(datum → syntax ctxt v [srcloc prop ignored) → syntax?
  ctxt : (or/c syntax? #f)
  v : any/c
   srcloc   :   ( or/c #f
> syntax?
> srcloc?
> ( list/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) )
> ( vector/c any/c
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f )
> ( or/c exact-positive-integer? #f )
> ( or/c exact-nonnegative-integer? #f ) ) )
      =   #f


# 12.2 Syntax Object Content
  prop : (or/c syntax? #f) = #f
  ignored : (or/c syntax? #f) = #f```
Converts the [datum](reader.html#%28tech._datum%29) v to a [syntax object](syntax-model.html#%28tech._syntax._object%29). If v is already a [syntax object](syntax-model.html#%28tech._syntax._object%29), then there is no conversion, and v is returned unmodified. The contents of pairs, vectors, and boxes, the values of immutable hash tables, and the fields of immutable [prefab](structures.html#%28tech._prefab%29) structures are recursively converted. The keys of [prefab](structures.html#%28tech._prefab%29) structures and the keys of immutable hash tables are not converted. Mutable vectors and boxes are replaced by immutable vectors and boxes. For any kind of value other than a pair, vector, box, immutable [hash table](hashtables.html#%28tech._hash._table%29), immutable [prefab](structures.html#%28tech._prefab%29) structure, or [syntax object](syntax-model.html#%28tech._syntax._object%29), conversion means wrapping the value with lexical information, source-location information, and properties after the value is [interned](reader.html#%28tech._interned%29) via [datum-intern-literal](#%28def._%28%28quote._~23~25kernel%29._datum-intern-literal%29%29).


# 12.2 Syntax Object Content
Converted objects in v are given the lexical context information of ctxt and the source-location information of srcloc. The resulting immediate [syntax object](syntax-model.html#%28tech._syntax._object%29) from conversion is given the properties (see [Syntax Object Properties](stxprops.html)) of prop (even the hidden ones that would not be visible via [syntax-property-symbol-keys](stxprops.html#%28def._%28%28quote._~23~25kernel%29._syntax-property-symbol-keys%29%29)); if v is a pair, vector, box, immutable [hash table](hashtables.html#%28tech._hash._table%29), or immutable [prefab](structures.html#%28tech._prefab%29) structure, recursively converted values are not given properties. If ctxt is [tainted](stxcerts.html#%28tech._tainted%29), then the resulting syntax object from [datum->syntax](#%28def._%28%28quote._~23~25kernel%29._datum-~3esyntax%29%29) is [tainted](stxcerts.html#%28tech._tainted%29). The [code inspector](modprotect.html#%28tech._code._inspector%29) of ctxt, if any, is compared to the code inspector of the module for the macro currently being transformed, if any; if both inspectors are available and if one is the same as or inferior to the other, then the result syntax has the same/inferior inspector, otherwise it has no code inspector.
Any of ctxt, srcloc, or prop can be #f, in which case the resulting syntax has no lexical context, source information, and/or new properties.