This issue was automatically generated. Feel free to close without ceremony if you do not agree with re-licensing or if it is not possible for other reasons. Respond to @cmr with any questions or concerns, or pop over to #rust-offtopic on IRC to discuss.

You're receiving this because someone (perhaps the project maintainer) published a crates.io package with the license as "MIT" xor "Apache-2.0" and the repository field pointing here.

TL;DR the Rust ecosystem is largely Apache-2.0. Being available under that license is good for interoperation. The MIT license as an add-on can be nice for GPLv2 projects to use your code.

Why?

The MIT license requires reproducing countless copies of the same copyright header with different names in the copyright field, for every MIT library in use. The Apache license does not have this drawback. However, this is not the primary motivation for me creating these issues. The Apache license also has protections from patent trolls and an explicit contribution licensing clause. However, the Apache license is incompatible with GPLv2. This is why Rust is dual-licensed as MIT/Apache (the "primary" license being Apache, MIT only for GPLv2 compat), and doing so would be wise for this project. This also makes this crate suitable for inclusion and unrestricted sharing in the Rust standard distribution and other projects using dual MIT/Apache, such as my personal ulterior motive, the Robigalia project.

Some ask, "Does this really apply to binary redistributions? Does MIT really require reproducing the whole thing?" I'm not a lawyer, and I can't give legal advice, but some Google Android apps include open source attributions using this interpretation. Others also agree with it. But, again, the copyright notice redistribution is not the primary motivation for the dual-licensing. It's stronger protections to licensees and better interoperation with the wider Rust ecosystem.

How?

To do this, get explicit approval from each contributor of copyrightable work (as not all contributions qualify for copyright, due to not being a "creative work", e.g. a typo fix) and then add the following to your README:

## License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.

and in your license headers, if you have them, use the following boilerplate (based on that used in Rust):

// Copyright 2016 coroutine-rs Developers
//
// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
// http://opensource.org/licenses/MIT>, at your option. This file may not be
// copied, modified, or distributed except according to those terms.

It's commonly asked whether license headers are required. I'm not comfortable making an official recommendation either way, but the Apache license recommends it in their appendix on how to use the license.

Be sure to add the relevant LICENSE-{MIT,APACHE} files. You can copy these from the Rust repo for a plain-text version.

And don't forget to update the license metadata in your Cargo.toml to:

license = "MIT OR Apache-2.0"

I'll be going through projects which agree to be relicensed and have approval by the necessary contributors and doing this changes, so feel free to leave the heavy lifting to me!

Contributor checkoff

To agree to relicensing, comment with :

I license past and future contributions under the dual MIT/Apache-2.0 license, allowing licensees to chose either at their option.

Or, if you're a contributor, you can check the box in this repo next to your name. My scripts will pick this exact phrase up and check your checkbox, but I'll come through and manually review this issue later as well.

• [x] @cristicbz
• [x] @doomsplayer
• [x] @izgzhen
• [x] @mnussbaum
• [x] @ra1u
• [x] @shepmaster
• [x] @zonyitoo

This is probably not the only api that is affected.

Right now:

• A coroutine may migrate from one thread to another
• A coroutine may yield inside of TLS with block.

Because of this, it is easy to build a simple test case that violates TLS rules.

extern crate coroutine;

use coroutine::{spawn, sched};
use std::cell::RefCell;

thread_local!(static LOCAL: RefCell<u32> = RefCell::new(7));

fn main() {
    let coro = spawn(move|| {
        LOCAL.with(|x| {
            *x.borrow_mut() += 1;
            let ptr: *const RefCell<u32> = x;
            println!("before: {:?} {:?} thread: {:?}", ptr, x, std::thread::current());
            sched();
            let ptr: *const RefCell<u32> = x;
            println!("after: {:?} {:?} thread: {:?}", ptr, x, std::thread::current());
        });
    });

    coro.resume().ok().expect("Failed to resume");

    std::thread::spawn(move || {
        coro.resume().ok().expect("Failed to resume");
    }).join().unwrap();
}

This will print:

before: 0x7f940205a728 RefCell { value: 8 } thread: Some("<main>")
after: 0x7f940205a728 RefCell { value: 8 } thread: None

Proposal to fix #31 With this PR I can compile simple example, but can't compile tls example:

extern crate coroutine;

use coroutine::asymmetric::Coroutine;
use std::cell::RefCell;

thread_local!(static LOCAL: RefCell<u32> = RefCell::new(7));

fn main() {
    let mut handle = Coroutine::spawn(move|cor| {
        LOCAL.with(|x| {
            *x.borrow_mut() += 1;
            let ptr: *const RefCell<u32> = x;
            println!("before: {:?} {:?} thread: {:?}", ptr, x, std::thread::current());
            cor.yield_with(0);
            let ptr: *const RefCell<u32> = x;
            println!("after: {:?} {:?} thread: {:?}", ptr, x, std::thread::current());
        });
    });

    (*handle).yield_with(0);

    std::thread::spawn(move || {
        (*handle).yield_with(0);
    }).join().unwrap();
}

Fails with:

   Compiling coroutine v0.5.0 (file:///home/denis/workspace/github.com/coroutine-rs)
examples/tls.rs:22:5: 22:23 error: the trait bound `*mut coroutine::asymmetric::Coroutine: std::marker::Send` is not satisfied [E0277]
examples/tls.rs:22     std::thread::spawn(move || {
                       ^~~~~~~~~~~~~~~~~~
examples/tls.rs:22:5: 22:23 help: run `rustc --explain E0277` to see a detailed explanation
examples/tls.rs:22:5: 22:23 note: `*mut coroutine::asymmetric::Coroutine` cannot be sent between threads safely
examples/tls.rs:22:5: 22:23 note: required because it appears within the type `coroutine::asymmetric::Handle`
examples/tls.rs:22:5: 22:23 note: required because it appears within the type `[closure@examples/tls.rs:22:24: 24:6 handle:coroutine::asymmetric::Handle]`
examples/tls.rs:22:5: 22:23 note: required by `std::thread::spawn`
error: aborting due to previous error
error: Could not compile `coroutine`.

PR #67 is great, but it has one imperfection: impossible to specify return value when coroutine ends (it return usize::MAX by default. I use library dinamically and take segfaults, because resume expects valid value anytime. We can solve it if closure will return value explicitly, but it makes API quite ugly and forces users to rewrite more code.

Another ides I tried:

• Check usize::MAX value, but I have to return additional data.
• If I will use explicit yield on tail, coroutine will contains invalid is_finished status.

I've made this PR to solve mentioned problems in better way. This PR takes profits:

1. Add possibility to get initial value of first resume call (by get_first method of Coroutine)
2. Add possibility to set final value when coroutine ends to last resume call (by set_last method of Coroutine)
3. Revert closure type to FnOnce(&mut Coroutine) to prevent user's code changing

It's more user-friendly, because API not changed and nobody have to change closures, but anyone can control first and last value explicitly.

@zonyitoo It needs your resoulition.

What if two different threads got a Handle to the same Coroutine and then try to resume it concurrently?

There are multiple choices to apply for this situation:

1. Make the Handle non-Clonable. This is the most simple solution, but I am still wondering whether it is applicable for most situation.
   • It may not be possible to get a Handle to the current running Coroutine. Because the Environment doesn't own the Coroutine.
2. Add a conditional variable inside the Handle, when the Coroutine is running, other threads that wants to resume this Coroutine may have to wait for the signal. This solution allows the Handle be Clonable.

Do you have any plans/ideas how to implement pushing and pulling parameters between coroutines?

Something like this:

• http://www.boost.org/doc/libs/1_58_0/libs/coroutine/doc/html/coroutine/coroutine/asymmetric.html
• http://www.boost.org/doc/libs/1_58_0/libs/coroutine/doc/html/coroutine/coroutine/symmetric.html

The -rs suffix is redundant, since the fact that it's on crates.io already tells us it's Rust.

coroutine is still free on crates.io, so now's a great opportunity to grab the name.

For some reason whenever one of the coroutines created with this crate exit, my entire program also exits. Here is a simple test case that demonstrates the issue:

extern crate coroutine;
use coroutine::asymmetric::*;

fn main() {
    let mut c = Coroutine::spawn(move|h, data| {
        h.yield_with(0);
        h.yield_with(0);
        0
    });
    println!("{:?}", c.state());
    c.resume(0);
    println!("{:?}", c.state());
    c.resume(0);
    println!("{:?}", c.state());
    c.resume(0); // exits here
    println!("{:?}", c.state());
    println!("goodbye", );
}

Initial data on fisrt resuming is unsound and lost. It's important to take any piece data of resume send.

This PR fixes it, and makes possible to take value of first resume call.

It breaks backward compatibility, but not terrible.

@zonyitoo What's your opinion?

...
Build failed, waiting for other jobs to finish...
failed to run custom build command for `coroutine v0.3.2`
Process didn't exit successfully: `/home/vi/home/rust/coroutinetest/target/debug/build/coroutine-58be77db9ec74666/build-script-build` (exit code: 101)
--- stderr
thread '<main>' panicked at 'Unsupported architecture: i686-unknown-linux-gnu', /home/vi/home/rust/.cargo/registry/src/github.com-48ad6e4054423464/coroutine-0.3.2/build.rs:21

$ rustc --version
rustc 1.7.0-nightly (2b8e96dad 2015-12-21)

i686 is listed in README although.

When compiled with nightly rustc, this line will report error:

src/asymmetric.rs:271:57: 271:74 error: mismatched types:
 expected `*mut libc::types::common::c95::c_void`,
    found `Box<[closure@src/asymmetric.rs:220:23: 269:10 puller_ref:_, f:_, coro_ref:_]>`
(expected *-ptr,
    found box) [E0308]    
src/asymmetric.rs:271         coro.context.init_with(coroutine_initialize, 0, Box::new(wrapper), &mut stack);

I searched a bit and find a solution from this post: change Box::new(wrapper) into &wrapper as *const _ as *mut libc::c_void

It compiled. But honestly, I am not very familiar with low-level rust so I have no idea why the Box::new is wrong and this casting is right.

error[E0432]: unresolved import `std::boxed::FnBox`
  --> /_/code/.cache_rust/registry/src/github.com-1ecc6299db9ec823/coroutine-0.8.0/src/asymmetric.rs:25:5
   |
25 | use std::boxed::FnBox;
   |     ^^^^^^^^^^^^^^^^^ no `FnBox` in `boxed`

error[E0554]: `#![feature]` may not be used on the stable release channel
  --> /_/code/.cache_rust/registry/src/github.com-1ecc6299db9ec823/coroutine-0.8.0/src/lib.rs:25:12
   |
25 | #![feature(fnbox)]
   |            ^^^^^

error[E0635]: unknown feature `fnbox`
  --> /_/code/.cache_rust/registry/src/github.com-1ecc6299db9ec823/coroutine-0.8.0/src/lib.rs:25:12
   |
25 | #![feature(fnbox)]
   |            ^^^^^

after adding it to toml.

Thank you for creating coroutine-rs

I'm just learning, but it seems Rust has some form of either: coroutines, semiroutines or generators, as was implemented to build async/await into Rust.

Generators Pull Request Claim futures/await is build upon generators/coroutines

It would be really lovely if the README had some explanatory text discussing the currently use cases for this package. Where it shines, where it might make sense to use Rust core features.

It's really very hard to figure out the should I use features from this Crate, or build in Rust features as a newcomer to the Rust world.

The text "Thread-safe: can only resume a coroutine in one thread simultaneously" in the readme.md might scare people away. Is this meant to mean "does not implement send and/or sync yet" or "it is inherently unsafe to use in multiple threads"?

Can't compile in windows without std::mem import.

stack_protected.rs

#[cfg(windows)]
fn page_size() -> usize {
    unsafe {
        let mut info = mem::zeroed(); // this fails
        libc::GetSystemInfo(&mut info);
        info.dwPageSize as usize
    }
}