Threads and services
Slide 47 of 85
47spawnThreads and services

Services

A service is a piece of state with a mailbox, reached by its Address<M> — M being the messages it takes — from this process or another machine by the same statement. Three builtins do the work:

  • spawn(handler, state) starts one and answers with a Result<Address<M>, hive.syslink.SyslinkError>, M read off the handler; spawn(handler, state, #Name) also registers it under an atom, and fails as Taken if another service holds the name.
  • at(#Name) is the service registered under that name here, and at(endpoint, #Name) the one on another node — building an address, looking nothing up. A name says nothing about what the service takes, so at takes its M from where it lands — Address<Note> box = at(#Cache) — or, bound with :=, from its first later send, and keeps it.
  • kill(address) stops one, on any node; killing one twice is harmless, and its name is free again before anybody hears it stopped.

A handler is one turn, proc(state: mut S, msg: M): M: it writes the state in place and answers with a message of its own type, and it may take a third parameter, its own Address<M>, to hand to work it starts. Only the service's mailbox ever holds the state, one message at a time, so nothing needs a lock — and a test calls a handler directly with a mut variable of its own. A handler whose branches each return, in one chain covering the message type, turns a message added later into a compile error.

Calling an address is a request: box(msg) waits for the answer, as a Result<M, SyslinkError>, up to five seconds unless with timeout says otherwise; async box(msg) sends and forgets, its answer dropped; x := async box(msg) and await [a(m), b(m)] send now and wait later. A request that times out still waits its turn in the mailbox, ahead of the ones behind it. An address carries its message type, so a message of the wrong type is a compile error; one sent to a name whose service takes something else fails when it arrives, as Decode. A panic in a handler kills only that service — the node says hive: service Counter crashed: … on stderr, its callers are told Down, and hive.syslink.monitor(watcher, target, notice) posts notice to a service on this node when target stops. A named address outlives its service: spawn a new one under the name, and the old address reaches it. An anonymous one dies with it.

Every failure says which it was, as a variant of SyslinkError: Taken, Down, NoProc for a name nothing holds, Timeout, Unreachable, Decode, and, across nodes, NoPeer, NoListener and NoKey — so a switch over one covers every way a request can fail.

A service on this node
type Note {
	Say   { text: Str }
	Count
	Total { count: Int }
}

proc tally(state: mut Int, msg: Note): Note {
	if msg is Note.Say(text) {
		echo text
		return msg
	} else if msg is Note.Count {
		state += 1
		return Note.Total(state)
	} else if msg is Note.Total(_) {
		return msg
	}
}

proc main(): void {
	if spawn(tally, 0, #Cache) is Result.Error(err) {
		panic err
	}
	Address<Note> address = at(#Cache)

	async address(Note.Say("hi"))                    // fire and forget
	reply := address(Note.Count()) with timeout 250   // send and wait, bounded
	if reply is Result.Ok(msg) {
		echo msg
	}
}
Slow work, off the turn
type Note {
	Fetch
	Fetched { text: Str }
	Latest
	Answer  { text: Str }
}

proc desk(latest: mut Str, note: Note, me: Address<Note>): Note {
	if note is Note.Fetch {
		async fetch(me)                // the turn ends now
		return Note.Answer("started")
	} else if note is Note.Fetched(text) {
		latest = text                  // the result arrives as a message
		return note
	} else if note is Note.Latest {
		return Note.Answer(latest)
	} else if note is Note.Answer(_) {
		return note
	}
}

proc fetch(back: Address<Note>): void {
	hive.task.sleep(300)
	async back(Note.Fetched("worth the wait"))
}

proc main(): void {
	if spawn(desk, "nothing yet") is Result.Ok(box) {
		if box(Note.Fetch()) with timeout 500 is Result.Ok(now) { echo now }
		if box(Note.Latest()) with timeout 500 is Result.Ok(first) { echo first }
		hive.task.sleep(500)
		if box(Note.Latest()) with timeout 500 is Result.Ok(later) { echo later }
	}
}