Documentation
¶
Overview ¶
Package refs defines an interface for reference counted objects. It also provides a drop-in implementation called AtomicRefCount.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AtomicRefCount ¶
type AtomicRefCount struct {
// contains filtered or unexported fields
}
AtomicRefCount keeps a reference count using atomic operations and calls the destructor when the count reaches zero.
N.B. To allow the zero-object to be initialized, the count is offset by
1, that is, when refCount is n, there are really n+1 references.
func (*AtomicRefCount) DecRef ¶
func (r *AtomicRefCount) DecRef()
DecRef decrements this object's reference count.
func (*AtomicRefCount) DecRefWithDestructor ¶
func (r *AtomicRefCount) DecRefWithDestructor(destroy func())
DecRefWithDestructor decrements the object's reference count. If the resulting count is negative and the destructor is not nil, then the destructor will be called.
Note that speculative references are counted here. Since they were added prior to real references reaching zero, they will successfully convert to real references. In other words, we see speculative references only in the following case:
A: TryIncRef [speculative increase => sees non-negative references] B: DecRef [real decrease] A: TryIncRef [transform speculative to real]
func (*AtomicRefCount) IncRef ¶
func (r *AtomicRefCount) IncRef()
IncRef increments this object's reference count. While the count is kept greater than zero, the destructor doesn't get called.
The sanity check here is limited to real references, since if they have dropped beneath zero then the object should have been destroyed.
func (*AtomicRefCount) TestReadRefs ¶
func (r *AtomicRefCount) TestReadRefs() int64
TestReadRefs returns the current reference count of r. Use only for tests.
func (*AtomicRefCount) TryIncRef ¶
func (r *AtomicRefCount) TryIncRef() bool
TryIncRef attempts to increment the reference count, *unless the count has already reached zero*. If false is returned, then the object has already been destroyed, and the weak reference is no longer valid. If true if returned then a valid reference is now held on the object.
To do this safely without a loop, a speculative reference is first acquired on the object. This allows multiple concurrent TryIncRef calls to distinguish other TryIncRef calls from genuine references held.
type RefCounter ¶
type RefCounter interface {
// IncRef increments the reference counter on the object.
IncRef()
// DecRef decrements the reference counter on the object.
//
// Note that AtomicRefCounter.DecRef() does not support destructors.
// If a type has a destructor, it must implement its own DecRef()
// method and call AtomicRefCounter.DecRefWithDestructor(destructor).
DecRef()
// TryIncRef attempts to increase the reference counter on the object,
// but may fail if all references have already been dropped. This
// should be used only in special circumstances, such as WeakRefs.
TryIncRef() bool
// contains filtered or unexported methods
}
RefCounter is the interface to be implemented by objects that are reference counted.
type WeakRef ¶
WeakRef is a weak reference.
func NewWeakRef ¶
func NewWeakRef(rc RefCounter, u WeakRefUser) *WeakRef
NewWeakRef acquires a weak reference for the given object.
An optional user will be notified when the last non-weak reference is dropped.
Note that you must hold a reference to the object prior to getting a weak reference. (But you may drop the non-weak reference after that.)
func (*WeakRef) Drop ¶
func (w *WeakRef) Drop()
Drop drops this weak reference. You should always call drop when you are finished with the weak reference. You may not use this object after calling drop.
func (*WeakRef) Get ¶
func (w *WeakRef) Get() RefCounter
Get attempts to get a normal reference to the underlying object, and returns the object. If this fails (the object no longer exists), then nil will be returned instead.
type WeakRefUser ¶
type WeakRefUser interface {
// WeakRefGone is called when the last non-weak reference is dropped.
WeakRefGone()
}
A WeakRefUser is notified when the last non-weak reference is dropped.
Source Files