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, a dtrace message similar to the following example is generated:
dtrace: 2 failed speculations (no speculative buffer space available)
The number of speculative buffers defaults to one, but may be optionally tuned higher. See Speculation Options and Tuning for more information.