3.14.3 Generators

A generator is a procedure that returns a sequence of values, incrementing the sequence each time that the generator is called. In particular, the generator form implements a generator by evaluating a body that calls yield to return values from the generator.

For the first call to a generator, the arguments are bound to the formals and evaluation of body starts. During the dynamic extent of body, the generator can return immediately using the yield function. A second call to the generator resumes at the yield call, producing the arguments of the second call as the results of the yield, and so on. The eventual results of body are supplied to an implicit final yield; after that final yield, calling the generator again returns the same values, but all such calls must provide 0 arguments to the generator.

When not in the dynamic extent of a generator, infinite-generator, or in-generator body, yield raises exn:fail after evaluating its exprs.

If in-generator is used immediately with a for (or for/list, etc.) binding’s right-hand side, then its result arity (i.e., the number of values in each element of the sequence) can be inferred. Otherwise, if the generator produces multiple values for each element, its arity should be declared with an #:arity arity-k clause; the arity-k must be a literal, exact, non-negative integer.

To use an existing generator as a sequence, use in-producer with a stop-value known for the generator:

> (define abc-generator (generator ()                          (for ([x '(a b c)])                             (yield x))))

> (for/list ([i (in-producer abc-generator (void))])     i)

'(a b c)

> (define my-stop-value (gensym))

> (define my-generator (generator ()                          (let loop ([x (list 'a (void) 'c)])                            (if (null? x)                                my-stop-value                                (begin                                  (yield (car x))                                  (loop (cdr x)))))))

> (for/list ([i (in-producer my-generator my-stop-value)])     i)

'(a #<void> c)

• 'fresh — The generator has been freshly created and has not been called yet.

• 'suspended — Control within the generator has been suspended due to a call to yield. The generator can be called.

• 'running — The generator is currently executing.

• 'done — The generator has executed its entire body and will continue to produce the same result as from the last call.