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 speculative buffer is unavailable 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. For more information, see Speculation Options and Tuning.