Examples: alternative roadmaps?

[liyishuai]

Thank you for the nice examples! I wonder if an alternative roadmap of presenting the examples might help the readers better apply this framework to their projects:

Current roadmap:

1. In-process echo
2. In-process echo + callback
3. Network echo + callback + network server in the same program
4. Network echo + callback + network server in different programs

Suppose I want "Basic echo + network server in different programs", I should first learn from (1) about how to write a .capnp file, and then go directly to (4), and strip away the callback and heartbeat parts.

I doubt if anyone would want to run a network server and a client in the same process, so (3) doesn't seem informative.

Does it make sense to roadmap as follows?

1. Syntax: How to write a basic .capnp file, and validate its functionality in an in-process echo example? (above 1)
2. Network: How to split the echo into different programs? (above 4 minus 2)
3. Semantics: How to make the protocol more interesting? (above 2)

Now the user may try any path: either (i) 1 -> 1+2 -> 1+2+3; or (ii) 1 -> 1+3 -> 1+3+2.

[talex5]

It could certainly work either way. The main problem is that separate processes are harder to experiment with because you have to recompile both binaries and restart them both each time you change something, and you get confusing output if you forget.

It might make sense to have the reader run the final example at the start of the tutorial so they can see what it's leading up to and copy it if they're in a hurry. But it's unusual to want to use capnp-rpc without the special features.

[liyishuai]

It might make sense to have the reader run the final example at the start of the tutorial so they can see what it's leading up to and copy it if they're in a hurry.

That's what I attempted, but failed at "how do I modify the example (e.g. remove the heartbeats) and make it still compile?"

But it's unusual to want to use capnp-rpc without the special features.

Yes we need the special features sooner or later. The current issue is the order of learning things: I'd hope to see a minimal example where programs on separate machines talk to each other---say, one client talking to five servers---before designing the callback function that computes over the reponses from the five servers.