API simplification in tomb package

247 views

Skip to first unread message

Gustavo Niemeyer

unread,

Oct 23, 2011, 3:48:59 PM10/23/11

to golang-nuts

Greetings,

I just issued an update to the tomb package described in the following post:

http://blog.labix.org/2011/10/09/death-of-goroutines-under-control

It is a simplification on the API based on actual usage, and it's not
compatible with the previous interface, so I'd like to describe what
was done and why in case you're already putting it to use.

The core change revolves around clean termination of goroutines.
Instead of doing t.Fatal(nil), one should now use t.Fatal(tomb.Stop).
This improves the API in two ways: first, it enables Fatal to panic in
case a nil error is provided erroneously (that's the case now); and
second, it means that calling t.Err() will always yield a non-nil
error in case a Tomb is flagging the goroutine as dying or dead.

As a nice side effect, loops that might previously be written as:

for !t.IsDying() {...}

Can now be written conveniently and slightly more idiomatically as:

for t.Err() == nil {...}

That also means the IsDying and IsDead methods aren't so interesting
anymore, and so they're both gone. The Wait method also takes Stop
into consideration, and returns nil in case the goroutine terminated
cleanly.

Here is as a summary of these changes:

- t.Fatal(tomb.Stop) should be used in place of t.Fatal(nil)
- t.Fatal(nil) now panics
- t.Err() is guaranteed to return an error if the goroutine is dying or dead
- t.Wait() returns nil if reason was Stop
- t.IsDying() and t.IsDead() are both gone

The aforementioned blog post was also updated to reflect the new API.

--
Gustavo Niemeyer
http://niemeyer.net
http://niemeyer.net/plus
http://niemeyer.net/twitter
http://niemeyer.net/blog