libgo/go/sync/once.go

   1 // Copyright 2009 The Go Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style
   3 // license that can be found in the LICENSE file.
   4
   5 package sync
   6
   7 import (
   8         "sync/atomic"
   9 )
  10
  11 // Once is an object that will perform exactly one action.
  12 //
  13 // A Once must not be copied after first use.
  14 type Once struct {
  15         // done indicates whether the action has been performed.
  16         // It is first in the struct because it is used in the hot path.
  17         // The hot path is inlined at every call site.
  18         // Placing done first allows more compact instructions on some architectures (amd64/386),
  19         // and fewer instructions (to calculate offset) on other architectures.
  20         done uint32
  21         m    Mutex
  22 }
  23
  24 // Do calls the function f if and only if Do is being called for the
  25 // first time for this instance of Once. In other words, given
  26 //      var once Once
  27 // if once.Do(f) is called multiple times, only the first call will invoke f,
  28 // even if f has a different value in each invocation. A new instance of
  29 // Once is required for each function to execute.
  30 //
  31 // Do is intended for initialization that must be run exactly once. Since f
  32 // is niladic, it may be necessary to use a function literal to capture the
  33 // arguments to a function to be invoked by Do:
  34 //      config.once.Do(func() { config.init(filename) })
  35 //
  36 // Because no call to Do returns until the one call to f returns, if f causes
  37 // Do to be called, it will deadlock.
  38 //
  39 // If f panics, Do considers it to have returned; future calls of Do return
  40 // without calling f.
  41 //
  42 func (o *Once) Do(f func()) {
  43         // Note: Here is an incorrect implementation of Do:
  44         //
  45         //      if atomic.CompareAndSwapUint32(&o.done, 0, 1) {
  46         //              f()
  47         //      }
  48         //
  49         // Do guarantees that when it returns, f has finished.
  50         // This implementation would not implement that guarantee:
  51         // given two simultaneous calls, the winner of the cas would
  52         // call f, and the second would return immediately, without
  53         // waiting for the first's call to f to complete.
  54         // This is why the slow path falls back to a mutex, and why
  55         // the atomic.StoreUint32 must be delayed until after f returns.
  56
  57         if atomic.LoadUint32(&o.done) == 0 {
  58                 // Outlined slow-path to allow inlining of the fast-path.
  59                 o.doSlow(f)
  60         }
  61 }
  62
  63 func (o *Once) doSlow(f func()) {
  64         o.m.Lock()
  65         defer o.m.Unlock()
  66         if o.done == 0 {
  67                 defer atomic.StoreUint32(&o.done, 1)
  68                 f()
  69         }
  70 }