Decorator to create non-blocking sample methods.

Some samplers work asynchronously, and it is useful for composites to handle that case. This decorator can be used to easily construct a non-blocking Sampler or Composite.

The function being decorated must return an iterator when called. This iterator must yield exactly two values.

The first value can be any object, but if the object has a done() method, that method will determine the value of SampleSet.done().

The second value must be a SampleSet, which will provide the samples to the user.

The generator is executed until the first yield. The generator is then resumed when the returned sample set is resolved.

>>> from dimod.decorators import nonblocking_sample_method
>>> class Sampler:
...     @nonblocking_sample_method
...     def sample(self, bqm):
...         print("First part!")
...         yield
...         print("Second part!")
...         sample = {v: 1 for v in bqm.variables}
...         yield dimod.SampleSet.from_samples_bqm(sample, bqm)
>>> bqm = dimod.BinaryQuadraticModel.from_ising({'a': -1}, {('a', 'b'): 1})
>>> ss = Sampler().sample(bqm)
First part!
>>> ss.resolve()
Second part!
>>> print(ss)
   a  b energy num_oc.
0 +1 +1    0.0       1
['SPIN', 1 rows, 1 samples, 2 variables]