README
¶
gcnotifier
gcnotifier provides a way to receive notifications after every run of the garbage collector (GC). Knowing when GC runs is useful to instruct your code to free additional memory resources that it may be using.
Why?
Package gcnotifier provides a way to receive notifications after every garbage collection (GC) cycle. This can be useful, in long-running programs, to instruct your code to free additional memory resources that you may be using.
A common use case for this is when you have custom data structures (e.g. buffers, rings, trees, pools, ...): instead of setting a maximum size to your data structure you can leave it unbounded and then drop all (or some) of the allocated-but-unused slots after every GC run (e.g. sync.Pool drops all allocated-but-unused objects in the pool during GC).
To minimize the load on the GC the code that runs after receiving the notification should try to avoid allocations as much as possible, or at the very least make sure that the amount of new memory allocated is significantly smaller than the amount of memory that has been "freed" by your code.
GCNotifier guarantees to send a notification after every GC cycle completes. Note that the Go runtime does not guarantee that the GC will run: specifically there is no guarantee that a GC will run before the program terminates.
How to use it
The simplest use of this library is as follows:
gcn := gcnotifier.New()
for range gcn.AfterGC() {
// this code will be executed after every GC cycle
}
runtime.KeepAlive(gcn) // or store gcn somewhere to keep it alive
As written, the loop above will never terminate, so it is mostly useful if you have global caches that persist for the whole duration of the process.
Note that the AfterGC() call is not guarantee to keep gcn alive. gcn and any channel
returned by AfterGC() will automatically get closed if gcn is garbage collected.
So if gcn is not kept alive, the for loop will terminate unexpectedly.
If you want to ensure the loop above terminates (e.g. because you only need the
notifications for the lifetime of a different object) you can call the
Close() method:
gcn := gcnotifier.New()
go func() {
for range gcn.AfterGC() {
// this code will be executed after every GC cycle
// until Close() is called
}
}()
// later, or elsewhere in your code
gcn.Close() // the loop above will terminate some time after this call
Note that if a loop iteration takes longer than the interval between two GC cycles it is possible that one notification will be dropped. Followup notifications will be still received correctly.
For a more complex example of how to use it have a look at Example() in
gcnotifier_test.go.
For details have a look at the documentation.
How it works
gcnotifier uses finalizers to know when a GC run has completed.
Finalizers are run when the garbage collector finds an unreachable block with an associated finalizer.
The SetFinalizer documentation notes that there is no guarantee that
finalizers will run before a program exits. This doesn't mean, as
sometimes incorrectly understood, that finalizers are not guaranteed to run at
all, it just means that they are not guaranteed to run because GC itself is not
guaranteed to run in certain situations: e.g. when the runtime is shutting down.
Finalizers can also not run for other reasons (e.g. zero-sized or
package-level objects) but they don't apply to gcnotifier because care was
taken in the implementation to avoid them.
The only other case in which a notification will not be sent by gcnotifier is if your code hasn't consumed a previously-sent notification. In all other cases if a GC cycle completes your code will receive a notification.
The test in gcnotifier_test.go generates garbage in a loop and makes sure that we receive exactly one notification for each of the first 500 GC runs. In my testing I haven't found a way yet to make gcnotifier fail to notify of a GC run short of shutting down the process or failing to receive the notification. If you manage to make it fail in any other way please file a GitHub issue.
License
Author
Carlo Alberto Ferraris (@cafxx)
Documentation
¶
Overview ¶
Package gcnotifier provides a way to receive notifications after every garbage collection (GC) cycle. This can be useful, in long-running programs, to instruct your code to free additional memory resources that you may be using.
A common use case for this is when you have custom data structures (e.g. buffers, caches, rings, trees, pools, ...): instead of setting a maximum size to your data structure you can leave it unbounded and then drop all (or some) of the allocated-but-unused slots after every GC run (e.g. sync.Pool drops all allocated-but-unused objects in the pool during GC).
To minimize the load on the GC the code that runs after receiving the notification should try to avoid allocations as much as possible, or at the very least make sure that the amount of new memory allocated is significantly smaller than the amount of memory that has been "freed" in response to the notification.
GCNotifier guarantees to send a notification after every GC cycle completes. Note that the Go runtime does not guarantee that the GC will run: specifically there is no guarantee that a GC will run before the program terminates.
Example ¶
Example implements a simple time-based buffering io.Writer: data sent over dataCh is buffered for up to 100ms, then flushed out in a single call to out.Write and the buffer is reused. If GC runs, the buffer is flushed and then discarded so that it can be collected during the next GC run. The example is necessarily simplistic, a real implementation would be more refined (e.g. on GC flush or resize the buffer based on a threshold, perform asynchronous flushes, properly signal completions and propagate errors, adaptively preallocate the buffer based on the previous capacity, etc.)
dataCh := make(chan []byte)
doneCh := make(chan struct{})
out := ioutil.Discard
go func() {
var buf []byte
var tick <-chan time.Time
gcn := New()
for {
select {
case data := <-dataCh:
if tick == nil {
tick = time.After(100 * time.Millisecond)
}
// received data to write to the buffer
buf = append(buf, data...)
case <-tick:
// time to flush the buffer (but reuse it for the next writes)
if len(buf) > 0 {
out.Write(buf)
buf = buf[:0]
}
tick = nil
case <-gcn.AfterGC():
// GC just ran: flush and then drop the buffer
if len(buf) > 0 {
out.Write(buf)
}
buf = nil
tick = nil
case <-doneCh:
// close the writer: flush the buffer and return
if len(buf) > 0 {
out.Write(buf)
}
return
}
}
}()
for i := 0; i < 1<<20; i++ {
dataCh <- make([]byte, 1024)
}
doneCh <- struct{}{}
Output:
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type GCNotifier ¶
type GCNotifier struct {
// contains filtered or unexported fields
}
GCNotifier allows your code to control and receive notifications every time the garbage collector runs.
func (*GCNotifier) AfterGC ¶
func (n *GCNotifier) AfterGC() <-chan struct{}
AfterGC returns the channel that will receive a notification after every GC run. No further notifications will be sent until the previous notification has been consumed. To stop notifications immediately call the Close() method. Otherwise notifications will continue until the GCNotifier object itself is garbage collected. Note that the channel returned by AfterGC will be closed only when GCNotifier is garbage collected. The channel is unique to a single GCNotifier object: use dedicated GCNotifiers if you need to listen for GC notifications in multiple receivers at the same time.
func (*GCNotifier) Close ¶
func (n *GCNotifier) Close()
Close will stop and release all resources associated with the GCNotifier. It is not required to call Close explicitly: when the GCNotifier object is garbage collected Close is called implicitly. If you don't call Close explicitly make sure not to accidently maintain the GCNotifier object alive.
Source Files