Overview
After reading through this basic overview, you may want to check out the tutorials page and go through a couple of them.
Many conventional languages separate code that runs on different hosts into different files. For instance, if you were to express the sequence of messages between a requester and server below:
in C++, your project might look as follows:
(where the grey, orange, pink, and blue bits of message exchange code are interleaved with code for generating other types of messages or other operations).
Waldo takes a different approach. It combines code from multiple endpoints into a single file. The compiler then partitions this code into two separate files that can be imported separately using the target language's standard library mechanisms:
There are several different connection types in Waldo. For the most common type of connection, a TCP connection, one host listens on a port and the other side tries to connect to that port. Just as a user needs to know the name of a Web page before entering it into a Web browser, a connecting client must know the port number to connect to before connecting. For example, to set up the server/requester above, your code might look as follows:
Server code:
from server import Server
import Waldo
...
Waldo.tcp_accept(SERVER_HOSTNAME,SERVER_PORT_NUMBER, Server)
...
Requester code:
from requester import Requester
import Waldo
...
requester = Waldo.tcp_connect(SERVER_HOSTNAME,SERVER_PORT_NUMBER, Requester)
...
On connection, Waldo automatically creates and initializes Endpoint objects, which holds the logic and state for each side of a connection. (For more about Endpoint objects, see the tutorials pages.)
That's all there is to connection! After this, your Python code can make calls on the Server and Requester objects to exchange messages and update state held by the combined connection.
Real protocols frequently have associated state.
In TCP, state may be the next expected sequence number; on the Web, state might be a cookie stored on a client's browser; in a game, state might be a character's mesh, health, and other attributes. Waldo manages much of this state for the programmer. The runtime automatically synchronizes state between both sides and uses transactions to ensure that there are no read-write conflicts on concurrently running pieces of code. The type system page has more information on the replication guarantees that Waldo makes for different types of data.