sync: add OnceFunc, OnceValue, OnceValues

[adg]

This is a proposal for adding a generic OnceFunc function to the sync package in the standard library.

In my team's codebase we recently added this function to our private syncutil package:

// OnceFunc returns a function that invokes fn only once and returns the values
// returned by fn. The returned function may be called concurrently.
func OnceFunc[T any](fn func() (T, error)) func() (T, error)

(I put this in the (temporary) module github.com/adg/sync, if you want to try it out.)

This makes a common use of sync.Once, lazy initialization with error handling, more ergonomic.

For example, this Server struct that wants to lazily initialize its database connection may use sync.Once:

type Server struct {
	dbPath string

	dbInit sync.Once
	dbVal  *sql.DB
	dbErr  error
}

func NewServer(dbPath string) *Server {
	return &Server{
		dbPath: dbPath,
	}
}

func (s *Server) db() (*sql.DB, error) {
	s.dbInit.Do(func() {
		s.dbVal, s.dbErr = sql.Open("sqlite", s.dbPath)
	})
	return s.dbVal, s.dbErr
}

func (s *Server) DoSomething() error {
	db, err := s.db()
	if err != nil {
		return err
	}
	_ = db // do something with db
	return nil
}

While with OnceFunc a lot of the fuss goes away:

type Server struct {
	db func() (*sql.DB, error)
}

func NewServer(dbPath string) *Server {
	return &Server{
		db: sync.OnceFunc(func() (*sql.DB, error) {
			return sql.Open("sqlite", dbPath)
		}),
	}
}

func (s *Server) DoSomething() error {
	db, err := s.db()
	if err != nil {
		return err
	}
	_ = db // do something with db
	return nil
}

Playground links: before and after.

If there is interest in this, then I suppose it should first live in x/exp (as with the slices and maps packages) so that we can play with it.

This seems to me like a great example of how generics can be used in the standard library. I wasn't able to find an overall tracking bug for putting generics in the standard library, otherwise I'd have referenced it here.

[icholy]

Alternative API:

type Server struct {
	once sync.TryOnce[*sql.DB]
}

func (s *Server) db() (*sql.DB, error) {
	return s.once.Do(func() (*sql.DB, error) {
		return sql.Open("sqlite", dbPath)
	})
}

[earthboundkid]

I have one of these in https://github.com/carlmjohnson/syncx. I think it’s suitable for the standard library, but it should probably come as part of a std wide addition of generics, not a one off.

[cespare]

I played around with this in a large codebase. It's a nice idea.

I do prefer @icholy's API suggestion. It seems that the ergonomics are about the same and also that it would be a little harder to accidentally misuse. I could see people writing

func GetFoo() (*Foo, error) {
        return OnceFunc(getFoo)
}

whereas the equivalent mistake with TryOnce seems less likely (especially if people are used to sync.Once already). And in general, it just seems little nicer/more typical to have the shared state be a struct value rather than a function; for example, consider

var fooOnce TryOnce[*Foo]

func GetFoo() (*Foo, error) { return fooOnce.Do(getFoo) }

vs.

var getFooOnce = OnceFunc(getFoo)

func GetFoo() (*Foo, error) { return getFooOnce() }

When I was looking at how sync.Once gets used in my codebase, I found that I could categorize them roughly four ways:

1. A single return value (either no possibility of an error or else the error leads to os.Exit, log.Fatal, etc).
2. Two return values: (T, error).
3. No initialization values created (just a one-time check or something)
4. Multiple values initialized / a bunch of state configured

For (3) and (4), sync.Once seems about optimal right now. This proposal helps with (2). But I noticed that (1) is even more common than (2). So maybe having both would be best:

type OnceVal[T any] struct { /* ... */ }

func (o *OnceVal[T]) Do(f func() T) T

type OnceError[T any] struct { /* ... */ }

func (o *OnceError[T]) Do(f func() (T, error)) (T, error)

or even

type Once1[T any] struct { /* ... */ }

func (o *Once1[T]) Do(f func() T) T

type Once2[T1, T2 any] struct { /* ... */ }

func (o *Once2[T1, T2]) Do(f func() (T1, T2)) (T1, T2)

[earthboundkid]

FWIW, I wrote the closure version and find it much more ergonomic. It wouldn't occur to me to write

func GetFoo() (*Foo, error) {
        return OnceFunc(getFoo)
}

since it obviously should be var GetFoo = sync.OnceFunc(getFoo), but it's hard to predict what kind of error people will make en mass until it's in the wild.

[earthboundkid]

Also I don't think it makes sense for this to return an error for the reasons given here: #53696 (comment)

I also had a situation when I wanted to make some initialization in my app lazy (because it runs on Lambda and cold start is a pain) but the initialization could potentially fail, but once that's the situation, there's no good API (at least that I've seen). The errors have to be dealt with somewhere. (If they could be ignored, regular sync.Once would work.) If the system assumes initialization has already happened, the path to deal with the error isn't there and all you can do is crash. If it doesn't make that assumption, you need to handle the error every time you interact with the object, so it's not really "initialized" just "gettable".

[adg]

@carlmjohnson wrote:

The errors have to be dealt with somewhere. (If they could be ignored, regular sync.Once would work.) If the system assumes initialization has already happened, the path to deal with the error isn't there and all you can do is crash. If it doesn't make that assumption, you need to handle the error every time you interact with the object, so it's not really "initialized" just "gettable".

I proposed a OnceFunc that returns (T, error) because my code, and other code I have observed in the wild, often stores an initialization error alongside the initialized value.

A few examples I quickly pulled from the Go core (there are many more, I didn't want to look exhaustively):

• src/cmd/trace/main.go
• src/cmd/go/internal/auth/netrc.go
• src/cmd/go/internal/cache/default.go
• src/cmd/go/internal/modfetch/codehost/git.go
• src/cmd/go/internal/modfetch/sumdb.go
• src/cmd/internal/archive/archive_test.go

Your circumstances may call for a different error handling mechanism (crashing), but others prefer to handle the error every time the resource is requested. Then upstream callers can decide whether it's crash-worthy or not.

I think that without the error return value the proposed OnceFunc is not very useful. Otherwise you should just do the initialization earlier, since the program should crash if the resource isn't available anyway, or you don't care about handling the error in which case (as you say) the existing sync.Once gives you almost everything you need already.

[adg]

@icholy suggested:

Alternative API:

Let me just expand your suggested API to do exactly what the other examples are doing, so that it's a fair comparison:

type Server struct {
        dbPath string
        dbOnce sync.TryOnce[*sql.DB]
}

func NewServer(dbPath string) *Server {
        return &Server{dbPath: dbPath}
}

func (s *Server) db() (*sql.DB, error) {
        return s.dbOnce.Do(func() (*sql.DB, error) {
                return sql.Open("sqlite", s.dbPath)
        })
}

func (s *Server) DoSomething() error {
        db, err := s.db()
        ...
}

I like that the type has a usable zero value, which means you don't need a constructor for Server just to set up this value (but we do need the something to set the dbPath field, or whatever other state goes into the closure). However in exchange for that we need a wrapper function (the db method here), so we immediately return to equal in terms of boilerplate.

I like that baking the once-ness into the type declaration, instead of just using a plain closure, gives some indication on sight that it's a once-initialized value.

Here's a variation on what you suggest, which is arguably less boilerplatey, as we don't need to store the closure state anywhere. TheNewOnceFunc function returns a *OnceFunc[T] with a Do() (T, error) method:

type Server struct {
	db *sync.OnceFunc[*sql.DB]
}

func NewServer(dbPath string) *Server {
	return &Server{
		db: sync.NewOnceFunc(func() (*sql.DB, error) {
			return sql.Open("sqlite", dbPath)
		}),
	}
}

func (s *Server) DoSomething() error {
	db, err := s.db.Do()
	...
}

But to immediately argue against this: an advantage of baking the state (dbPath, in in this example) into the once function itself is that we don't expect that changing it later will have any effect. For instance, if we changed dbPath after the first call to the db function we might expect to access a different database. Putting that state in the closure makes it harder to make that mistake.

With all that said, my main objection to these proposals (compared to my original proposal) is that they make it harder to substitute a different initialization function that doesn't use OnceFunc. A central advantage of my original proposed API is that a sync.OnceFunc can wrap any func() (T, error) transparently, so that downstream callers don't know (and shouldn't care) that they're invoking it only once. In my experience this is a valuable property.

[adg]

@cespare my instinct is that having fewer things is better than more things. If someone wants to call a OnceFunc and ignore the error, they could just ignore the error.

[cespare]

However in exchange for that we need a wrapper function (the db method here)

I do think that a db method is nicer than a function as a struct field. That strikes me as unusual-looking about your original example.

Also, the original example doesn't look like the common use cases I see for sync.Once. I most often see sync.Once used for package-level initialization. That's what most of the links you located in #56102 (comment) are as well.

So we have something like this today:

var state struct {
	once sync.Once
	val *Thing
	err error
}

func State() (*Thing, error) {
	state.once.Do(func() {
		state.val, state.err = loadState()
	})
	return state.val, state.err
}

func loadState() (*Thing, error) { /* ... */ }

With OnceFunc, it could be

var loadStateOnce = sync.OnceFunc(loadState)

func State() (*Thing, error) {
	return loadStateOnce()
}

func loadState() (*Thing, error) { /* ... */ }

and with TryOnce, it would be

var loadStateOnce sync.TryOnce[*Thing]

func State() (*Thing, error) {
	return loadStateOnce.Do(loadState)
}

func loadState() (*Thing, error) { /* ... */ }

Neither has a real advantage in terms of conciseness. Adjusting either of these to get rid of the once-ness would be trivial.

One thing I notice about OnceFunc is that it might be tempting to save a few lines and write:

var State = sync.OnceFunc(loadState)

func loadState() (*Thing, error) { /* ... */ }

I think this would be a mistake, though. So both in your original example and here, OnceFunc seems to promote the use of function values in places where we would idiomatically use methods or normal functions in Go. OnceFunc seems like a function that would be very much at home in the functional languages I use, but not Go. (For instance it is available as memoize on a 0-ary function in Clojure.)