Related Issues

• runtime: AddCleanup does not panic if arg equals ptr #71316 (closed)
• cmd/compile: unsafe.{SliceData,StringData} possible memory corruption in escape analysis #57823 (closed)
• runtime: go runtime GC panic #45401 (closed)
• runtime: cgoCheckPointer fatal error: can't happen #70016 (closed)
• go build use -asan it panic. #69225 (closed)
• runtime: panic marked free object in span[1.17] #54247 (closed)
• runtime: Invalid garbage collection of structure pointers #36569 (closed)

Related Code Changes

• runtime: fix the equality check in AddCleanup
• runtime: implement AddCleanup

Related Documentation

• Package runtime > type Cleanup ¶ 1.24 > func AddCleanup ¶

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

We found a workaround by amending the definition of the outer type as follows:

FTR, the workaround will still result in the cleanup never running. Cleanups apply to contiguous blocks of memory, what we call an "object," not to Go values by the spec. The only fix is to have a pointer indirection:

type NeedsCleanup struct { ... }
func (c *NeedsCleanup) Close() { ... }

type Embeds struct {
  *NeedsCleanup
}

func New() *Embeds {
  var e Embeds
  e.NeedsCleanup = new(NeedsCleanup)
  runtime.AddCleanup(&e, (*NeedsCleanup).Close, e.NeedsCleanup)
  ...
  return &e
}

We don't panic in the workaround case you provided because we cannot easily catch all the cases where a reference from a cleanup back to the object is a problem. I do have a patch for a GODEBUG mode that identifies when cleanups will never run with absolute certainty and crashes the program, but it has a potentially non-trivial cost. (https://go.dev/cl/634599)

Thank you for clarifying. Would you folks be OK with potentially a few small amendments to the documentation for runtime.AddCleanup? A tracer shot example proposal:

From:

// If ptr is reachable from cleanup or arg, ptr will never be collected and the cleanup will never run.
// As a protection against simple cases of this, AddCleanup panics if arg is equal to ptr.

To:

// If ptr is reachable from cleanup or arg, ptr will never be collected and the cleanup will never run.
// As a protection against simple cases of this, AddCleanup panics if arg is equal to ptr.  ptr still counts
// as being reachable if arg points to something in ptr's memory space, as would be the case with
// struct fields.  A workaround in the struct field case could be to use pointer indirection instead:
//
//  type Client struct {
//    r *resource
//  }
//
//  type resource struct { ... }
//
//  func (r *resource) Close() { ... }
//
//  func New() *Client {
//    c := &Client{r: &resource{...}}
//    runtime.AddCleanup(c, (*resource).Close, c.r)
//    return c
//  }

This is an API that I would rarely use, but I would really benefit from a plain language explanation about how to use it correctly and how not to.

Yes, please feel free to send a documentation change! (Or an example too, if you're up for it. :))

Change https://go.dev/cl/659975 mentions this issue: runtime: update AddCleanup documentation to note embedded data caveat