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 is discarded, the second must be a SampleSet.

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]