Exposing blocking API in golang?

Question

I have a golang library that abstracts a network service (think IRC-alike). The network server produces events which users of my library should consume. I'm using blocking network calls internally. I want to design my API to minimise friction users of my library, so i'm trying to decide between

• having the user supply func callbacks to mylib.doStuff(), which would enter my library's blocking network loop; it would be up to the caller to background this into a goroutine if they wished (and then perform their own synchronisation as necessary); or

• having the user call mylib.startDoingStuff(), which would spawn a background goroutine to handle the blocking network calls, returning multiple channels of events for the caller to select over. It has the advantage of isolating the goroutine and the blocking from the calling code.

What's more idiomatic? What would you expect to see in a network library?

Answer 1

I found a resource on the topic:

• https://inconshreveable.com/07-08-2014/principles-of-designing-go-apis-with-channels/
• https://www.reddit.com/r/golang/comments/2acr79/principles_of_designing_go_apis_with_channels/

In the end, i'm convinced a channel-based API is probably the way forward (at least for a v1 package), following the example of stdlib crypto/ssh.

However, the above link did strongly caution against implementing a channel-based API, mentioning a range of pitfalls (adequately describing buffer limits, edge case behavior, exhaustion behavior and so on)