The speculation function allocates a speculative buffer, and returns a speculation identifier. The speculation identifier should be used in subsequent calls to the speculate function. Speculative buffers are a finite resource: if no speculative buffer is available when speculation is called, an ID of zero is returned and a corresponding DTrace error counter is incremented. An ID of zero is always invalid, but may be passed to speculate, commit or discard. If a call to speculation fails, dtrace generates a message similar to the following example:

dtrace: 2 failed speculations (no speculative buffer space available)

The number of speculative buffers defaults to one, but can be optionally tuned higher. See Section 7.7, “Speculation Options and Tuning” for more information.