This is an archive of the discontinued LLVM Phabricator instance.

WIP Coroutine Documentation
AbandonedPublic

Authored by GorNishanov on Jun 8 2016, 10:15 PM.

Details

Reviewers
None
Summary

This is the first patch in the coroutine series. It contains the documentation for the coroutine intrinsics and their usage.

Diff Detail

Event Timeline

GorNishanov retitled this revision from to [coroutines] Part 1 of N: Documentation.
GorNishanov updated this object.
pitrou added a subscriber: pitrou.Jun 9 2016, 12:42 AM
pitrou added inline comments.
docs/Coroutines.rst
111

Shouldn't the first branch target be %cleanup, instead of %coro.return?

GorNishanov added inline comments.Jun 9 2016, 6:18 AM
docs/Coroutines.rst
111

coro.fork is currently specified so that:
the true branch leads to the place where control need to transfer if we hit suspend point.
the false branch leads to normal continuation.

I think you are right. It would be better to flip the meaning of true and false, so that normal branch is the first, and alternative is the second, same as coro.suspend and similar to invoke instruction.

Also, I was looking for a better name for coro.fork. Do you think coro.start would work better?

pitrou added inline comments.Jun 9 2016, 6:24 AM
docs/Coroutines.rst
111

My comment was related to the fact that the normal continuation branch should not skip the cleanup step (since the frame was allocated before, it needs to be deallocated).

As for the name, yes, coro.start() or perhaps coro.first() sounds better.

GorNishanov added inline comments.Jun 9 2016, 1:40 PM
docs/Coroutines.rst
111

coro.fork does not represent a suspend point. It is mostly there to indicate where to go when coroutine hits its very first suspend (while still running by the caller of 'f').

An alternative representation is to get rid of coro.fork altogether and replace coro.suspend with a terminator instruction with three possible successors.

Namely:

corosuspend [final] [save %token] to label %return.block
  resume label %resume
  cleanup label %cleanup

corosuspend is lowered as follows:

in 'f': corosuspend is replaced with `br %return.block`

in 'f.resume': 
  add a new entry block with a switch jumping to all resume blocks
  corosuspend is replaced with `ret void`

in 'f.destroy': 
  add a new entry block with a switch jumping to all cleanup blocks
  corosuspend is replaced with `ret void` (though this is not necessary since
  all corosuspends will be unreachable in the f.destroy and will be thrown out by
  SimplifyCFG

I think this makes understanding of the model clearer. The only negative side
to a corosuspend with three branching targets is that it is very likely that
to label block will be the same in all corosuspend's thus wasting valuable
bits. :-)

GorNishanov retitled this revision from [coroutines] Part 1 of N: Documentation to WIP [coroutines] Part 1 of N: Documentation.Jul 20 2016, 12:44 PM
GorNishanov retitled this revision from WIP [coroutines] Part 1 of N: Documentation to WIP Coroutine Documentation.Jul 20 2016, 12:53 PM

I started an official review of the llvm-commits:
https://reviews.llvm.org/D22603

I added the Python example.
I also added it to this review, so that it is easy to see what changed.

Please comment on https://reviews.llvm.org/D22603, not on this one.

GorNishanov abandoned this revision.Jul 21 2016, 7:35 PM

llvm-commits review is at: https://reviews.llvm.org/D22603