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)
	})
}

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.

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)

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.

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".

@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.

@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.

@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.

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.)

Actually the case in which I use it is globals; I chose the struct form as it's as slightly more complex context.

This is how you would use OnceFunc for your state example:

var state = sync.OnceFunc(func() (*Thing, error) {
        /* ... */
}

This IMO is way more concise than any of the alternatives.

(Sorry sent this before I had finished writing it.)

I think that function variables are fine in the context of private globals. If you wanted to export it and protect it from mutation outside the package, you could write:

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

var loadState = sync.OnceFunc(func() (*Thing, error) {
        /* ... */
})

OnceFunc seems to promote the use of function values in places where we would idiomatically use methods or normal functions in Go.

I think this kind of argument is not vey helpful in this context. We have new possibilities with generics; we should argue on the pros/cons, not by the established practices that pre-date the tools we have available today.

I think this kind of argument is not vey helpful in this context. We have new possibilities with generics; we should argue on the pros/cons, not by the established practices that pre-date the tools we have available today.

Ah -- I'd been taking it as self-evident that promoting function variables over functions should be avoided. My mistake.

I think that replacing functions with variables is a poor practice on the merits:

• Having multiple ways to do things is a burden on code writers and code readers. (As an occasional JavaScript writer I never know whether I should be declaring my functions using function or var.)
• The fact that a var is mutable means the reader of the code doesn't know whether the value has changed without locating all references to the var.
• The fact that a var is mutable opens the possibility of a data race if it is modified elsewhere.
• Using vars instead of functions further encourages mutating the var for testing purposes, an ill-advised practice that interferes with test parallelization and makes debugging harder.
• Invoking a function value through a var is slower than calling a function.
• The stack trace you get when calling a function through a var is less helpful (it doesn't include the var location).

Therefore, I think that APIs should not encourage using vars where functions or methods would have traditionally been used, and thus I think that a struct type is a better API here than a higher-order function.

I'd been taking it as self-evident that promoting function variables over functions should be avoided.

I think this is true, for most uses of global function variables, and most certainly exported ones. I'd go further to suggest that global variables as a whole are best avoided where possible.

But I don't think function variables should be avoided as a whole. For instance, look at this pitfall you describe:

Using vars instead of functions further encourages mutating the var for testing purposes, an ill-advised practice that interferes with test parallelization and makes debugging harder.

One good solution to this is to actually use a function variable, rather than mutating global state. For example, if you want to test some code that works with time, passing it a mock now func() time.Time (either as a function argument or by setting a struct field) allows you to control precisely what that function does in your tests.

So from here I'm assuming that function variables do have some value, and should be used where appropriate.

In the context of this proposal, where OnceFunc might be used to set a global function variable it would be replacing the use of three global variables. From your example:

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

I think, on the whole, if you're writing programs with globals like this then you're already vulnerable to most of the pitfalls you describe. If anything, OnceFunc makes it harder to make a mess of it. (This is why I chose to use the Server struct example, btw.)

Other concerns you raised:

Invoking a function value through a var is slower than calling a function.

That may be true in isolation but we'd need to benchmark the different approaches described here to make any efficiency arguments.

The stack trace you get when calling a function through a var is less helpful (it doesn't include the var location).

These stack traces seem equally helpful to me: before and after

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

This is clearly a very common operation that we should make easier. The only discussion seems to be whether to include the error in the function signature. So maybe there should be two forms: one with the error and one without. Generalizing "with error" to two values may make sense. But if so, what are the names? OnceVal / OnceError and Once1 / Once2 both seem a bit strange. Maybe we should find a name that's not "Once"?

sync.Lazy[T], sync.Lazy2[T] - lazy is maybe overused, or maybe it should have the function ahead of time
sync.Memo[T], sync.Memo2[T] - memoizing is usually parameterized, and this isn't
sync.Cache[T], sync.Cache2[T] - but caches can be cleared, and this can't

So lots of ideas, none of them great.

What about a single type with 2 methods:

type Memo[T any] struct {
	val  T
	err  error
	once sync.Once
}

func (m *Memo[T]) Do(f func() T) T {
	m.once.Do(func() {
		m.val = f()
	})
	return m.val
}

func (m *Memo[T]) DoErr(f func() (T, error)) (T, error) {
	m.once.Do(func() {
		m.val, m.err = f()
	})
	return m.val, m.err
}

This reminds me of #37739, but implemented with generics instead of as a language change and tailored specifically for use with concurrency. Maybe it makes sense to split the concurrency support out? In other words, have a lazy value interface somewhere non-concurrency specific and a sync.Lazy struct that wraps it to make it thread-safe?

package something

type Lazy[T any] interface {
  Eval() T
}

package sync

type Lazy[T any] struct {
  lazy something.Lazy[T]
}

To try to move things forward, what do people think of

type OnceValue[T any] struct { ... }
func (*OnceValue[T]) Do(func() T) T 

type OnceValueErr[T any] struct { ... }
func (*OnceValueErr[T]) Do(func() (T, error)) (T, error)

?

It seems like the name should begin with Once so that people find it when they are looking for sync.Once.

I think that two types is overkill. People can easily ignore the error return if they don't need it.

edit: I like the two type approach the best.

I prefer icholy's suggestion of one type with two methods to two types.

Having one type with two methods leaves open the possibility to use both with one OnceValue. That seems like a source of bugs. I can imagine legitimate ways to use both methods together, but the (T, error) form subsumes them.

Just to sum it up, here are the variations:

One type, one method:

type OnceValue[T any] struct { ... }
func (*OnceValue[T]) Do(func() (T, error)) (T , error)

Two types, one method:

type OnceValue[T any] struct { ... }
func (*OnceValue[T]) Do(func() T) T 

type OnceValueErr[T any] struct { ... }
func (*OnceValueErr[T]) Do(func() (T, error)) (T, error)

One type, two methods:

type OnceValue[T any] struct { ... }
func (*OnceValue[T]) Do(func() T) T 
func (*OnceValue[T]) DoErr(func() (T, error)) (T, error)

The one type, two methods version seems fine to me. To prevent misuse Do could panic if DoErr was previously called.

One type, two methods seems out-of-place, because you have to call one of the methods consistently to use it correctly.
If there are goroutines racing (this is package sync) and one calls Do and the other calls DoErr, then in at least one case we have a problem: when DoErr wins, caches an error, and then Do runs and can't return the error. That suggests that any valid use should either always call Do or always call DoErr. To avoid latent bugs that only show up in production, the implementation should probably panic any time it observes both methods being used.

So really there are two kinds of OnceValue: the kind that can only use Do, and the kind that can only use DoErr. Giving them the same Go type means the compiler can't help you make sure you are using the type correctly. In contrast, what we usually do in Go is use different types for different kinds of values, and then the type system and the compiler do help you, and this possible runtime panic is eliminated at compile time.

I think that excludes "one type, two methods".

"One type, one method" seems not quite right, because sometimes we will be caching things that can't possibly fail, and it's annoying to have to discard the error that can't happen anyway. Yes, code that can fail is common, but so is code that can't fail.

That leaves "two types, one method", which is why I suggested OnceValue and OnceValueErr.

Adding to what @rsc says in the comment just above--which I agree with--we do sometimes want to standardize on a method signature with an error return that may always be nil in some situations. That is often the right choice when we expect or know it will be common to define an interface for that method and we expect some implementations to need to return errors even if not all implementations will need to. io.Writer is a good example. The Write method returns an error, but there are implementations in the standard library and elsewhere that we know always return nil errors (e.g. *bytes.Buffer).

Is there enough value in both types of OnceValue implementing the same interface to make it worth the cost of sometimes ignoring errors (and making sure that's the correct choice) or sometimes checking for errors that will never happen?

My intuition in this case is that, no, there isn't much value in implementing a common interface here.

I implemented Russ' OnceValueErr type and updated the original example to use it:

type Server struct {
	dbPath string
	dbOnce sync.OnceValueErr[*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()
	if err != nil {
		return err
	}
	_ = db // do something with db
}

(playground)

Compared to the original proposal of a OnceFunc function that returns a function value:

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
}

I think that the proposed OnceValueErr type has several disadvantages over my proposed OnceFunc:

• OnceValueErr requires the use of another method through which you call its Do method. With OnceFunc there's just a db function value, and that's it.
• OnceValueErr requires you to specify the type T in both the OnceValueErr type spec and also in the function passed to Do. OnceFunc infers the type from the given closure.
• OnceValueErr is harder than OnceFunc to mock out in tests. With OnceFunc you can just substitute a different function value. With OnceValueErr you'd need to further abstract away the invocation of the Do method.

We use the io.Reader interface so that we can easily compose code that implements or uses io.Reader, without those different pieces of code needing to know about one another. The use of this well-defined interface is a great simplifying force. With OnceFunc I am proposing that we use the most well-defined interface in Go: the function.

In short: the purpose of my proposed OnceFunc is ergonomics. I see little benefit to the proposed OnceValue/OnceValueErr over the existing sync.Once.

OnceValueErr requires the use of another method through which you call its Do method. With OnceFunc there's just a db function value, and that's it.

If you were writing this code without the "once" behavior, a db method would be the idiomatic approach.

type Server struct {
	dbPath string
}

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

func (s *Server) db() (*sql.DB, error) {
	// TODO: reuse connection
	return sql.Open("sqlite", s.dbPath)
}

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

Deadlocking really feels like a foot-gun. For example, if you're in a context where panics are captured and thus not fatal, such as an HTTP handler or a test, I think deadlocking will cause very surprising behavior, such as causing later HTTP timeouts. While you can debug this from the goroutine stack trace, that's not nearly as obvious as simply getting a panic.

If we don't want to capture the panic value, I think a better alternative is for later calls to still panic, but with some other value that clearly indicates the first call panicked.

I agree with Austin: given the existence of widely-used standard libraries that swallow panics, repeating the panic seems more robust — and more in line with the general principle of “make concurrency an internal detail”.

Especially if the OnceFunc is an otherwise-idempotent function (memoized for efficiency instead of non-repeatability), it seems clearer for subsequent calls to re-panic with the original panic value than for them to deadlock.

Strictly speaking, we should probably also runtime.Goexit every caller if the original function call invoked runtime.Goexit. (To do that, we can use the “double defer sandwich” mentioned in #25448 (comment).)

Note that sync.Once originally did choice (2) call the function again. That was fixed as #8118.

Note also that this isn't going to come up much - most code won't recover the first panic.

That said, here are three reasons to choose re-panicking:

1. Go functions can do three possible things when you call them: return values, never return, or panic. We agree that if f returns values, future calls return those same values. We also agree that if f never returns, future calls never return. It stands to reason that if f panics, future calls should panic too. Otherwise we've collapsed three outcomes down to two for no apparent reason. (Okay, four possible things if you count runtime.Goexit. That was a mistake, though, and I'm happy to turn runtime.Goexit into a panic.)

2. If the first call was set up to recover from the panic, let's assume that was the right thing to do in that context, that recovering let the program continue on in a correct execution. Probably the second call will be in a similar context, ready to recover and proceed with a correct execution. Deadlocking instead breaks that second call.

3. Suppose that when the second call happens, the code is not prepared to recover from a panic. (Otherwise we're in (2).) Deadlocking does not really help debugging at all. Yes, it preserves the stack trace leading to the call, but the crash from re-panicking would show that stack trace too. And re-panicking would let the user see the actual panic message. Even if the user attaches to a deadlock in a debugger, if the panic wasn't saved from the first time, it's gone. There's less information in a deadlock than there is in a re-panic.

The current sync.Once panics on the first call, and simply doesn't make any subsequent calls. That is, it only calls the function once, even if the function panics.

https://go.dev/play/p/7FLrJotwaol

So that is another option here.

3. Suppose that when the second call happens, the code is not prepared to recover from a panic. (Otherwise we're in (2).) Deadlocking does not really help debugging at all. Yes, it preserves the stack trace leading to the call, but the crash from re-panicking would show that stack trace too. And re-panicking would let the user see the actual panic message. Even if the user attaches to a deadlock in a debugger, if the panic wasn't saved from the first time, it's gone. There's less information in a deadlock than there is in a re-panic.

Like many others, I implemented a similar function to do lazy initialization in an experimental generics library to test the functionality. I usually don't bother with it for long-running programs, since client startup time amortizes to insignificance, but it's particularly useful in cases like CLIs that might interact with some subset of a set of expensive clients, depending on the operation hierarchy. I ended up with two versions:

func Lazy[T any](initializer func() (T, error)) func() (T, error)
func MustLazy[T any](initializer func() (T, error)) func() T 

I found myself using the Must version far more often, in CLIs, since they spin up and down often and saving on total walltime is important. It was far more convenient to just

if err := myclient().ThatMethod("I", "need"); err != nil {
}

And to make sure to call log.Fatal in the initializer to avoid the need to panic. The method chaining is really convenient, and being able to avoid the boilerplate would be nice.

In both of my functions, I captured, re-threw and then threw the panic if called again with the reasoning that panics may be bad, but having them eaten is worse, and this is common enough that I needed to make sure it didn't happen, nor could it deadlock mysteriously.

I saved the stack trace as well, but that's arguably overkill.

There's a separate semi-serious proposal to add must.Get and must.Do to the standard library: #54297. If that existed, you could do var getT = sync.OnceValue(func() T { return must.Get(maybeT()) }).

Change https://go.dev/cl/479095 mentions this issue: cmd/compile: allow more inlining of functions that construct closures

Change https://go.dev/cl/481062 mentions this issue: sync: add examples for OnceValue and OnceValues

FYI: https://go.dev/cl/479095 had to be rolled back, due to problems encountered during google-internal testing (see #59404). Working now on resolving that.

Change https://go.dev/cl/482356 mentions this issue: cmd/compile: allow more inlining of functions that construct closures

Change https://go.dev/cl/484860 mentions this issue: cmd/compile: allow more inlining of functions that construct closures

CL 484860 broke the x/benchmarks builder: https://build.golang.org/?repo=golang.org%2fx%2fbenchmarks

Failure: https://build.golang.org/log/11803116ada45552b52ed62dd86f4255cdba5d87

What's happening is this call produces a closure that appears to be inlined into a compiler-generated init function. The closure it produces later gets installed here.

The end result is this function ends up dereferencing a nil pointer.

I reopened the issue in case we want to roll back this CL, but feel free to close and I can file a new issue instead.

Nevermind, filed #59680. Closing this issue.

Change https://go.dev/cl/492017 mentions this issue: cmd/compile: allow more inlining of functions that construct closures