document task scheduler

[jesse99]

task.rs is a bit overwhelming and very difficult to understand how to use correctly. I think it would be helpful to document a bit better the theory of operation, the default scheduling mode, and probably even some examples for common tasks (even if its just pointers to suitable unit tests).

For example just how are users supposed to deal with foreign code that blocks? In the simple case I guess SingleThreaded would do the trick. But what about more complex cases? What if I need to call a foreign blocking function, wait for it to respond, and then kick off a bunch of concurrent tasks? Is there a way to spawn that task with SingleThreaded without changing the scheduling of its child tasks?

[brson]

As far as your last question, there's no code to support this pattern yet, but the basic way to deal with this is to have the blocking task send spawn requests back to another task on the original scheduler.

[jesse99]

Some usage examples would certainly be handy, but this particular case is not hard. As best I can tell the blocking thread should be started with either SingleThreaded (if it spends most if its time blocked) or ManualThreads(1) (if it does substantial amounts of work between blocking).

When the blocking thread needs to spawn off new tasks it simply uses spawn_sched(ThreadPerCore) which will cause those tasks to share the default threads.

[brson]

SingleThreaded and ManualThreads(1) are identical. Calling spawn_sched(ThreadPerCore) will not cause the new tasks to go back to the default scheduler, it will create an entirely new scheduler for each call.

[brson]

I'm still hoping to get a full task tutorial in for 0.4 and improve the rustdocs.

[jesse99]

I think I understand how it's supposed to work now. Bit painful to spin up a task just to create sub-tasks elsewhere within the right scheduler. Also quite error prone and will require that I touch lots of code.

I think the answer in my case is to just use ManualThreads(small n) when I kick off a task to handle a new client connection. When that task needs to spawn sub-tasks it can just use task::spawn. More threads than I'd like but it's simple and should work reasonably well.

[sanxiyn]

Task tutorial now exists.

[catamorphism]

Nominating for milestone 4, well-covered (if there is still work to do on this).

[graydon]

accepted for well-covered milestone

[graydon]

I think this is suitably covered by the task tutorial; if not, it needs to be more specific about what docs are required (beyond "more always"; that's not specific enough to be a bug since it'll never close).

Meanwhile, closing this.