@Target(value=FIELD) @Retention(value=CLASS) public @interface RetainedWith
Weak over @RetainedWith if possible.
Indicates that the annotated field (child) forms a direct reference cycle
with the referring object (parent). Adding this annotation informs J2ObjC of
the reference cycle between the pair of objects allowing both objects to be
deallocated once there are no external references to either object.
@RetainedWith can be applied when a parent object pairs itself
with a child object and cannot fully manage the child's lifecycle, usually
because the child is returned to the caller. It can also be applied when the
child has the same class as the parent, for example on an inverse field of an
invertible collection type.
@RetainedWith can only be applied where there is a two-object pair
with a cycle created by one reference from each object. Note: the two
references can be from the same declared field. When the references are from
different fields only one field should be given a @RetainedWith annotation,
and the @RetainedWith field should point from parent to child.
When applied carefully in the right circumstance this annotation is very
useful in preventing leaks from certain Java collection types without needing
to alter their behavior.
The following criteria must be adhered to otherwise behavior will be
undefined:
- The child object must not reassign any references back to the parent
object. Preferably references from child to parent are declared final.
- The child object must not contain any Weak references back to the
parent object.
- The child object must not be available to other threads at the time of
assignment. (Normally, the cycle is created upon construction of the child)Copyright © 2017. All rights reserved.