001/*
002 * Licensed under the Apache License, Version 2.0 (the "License");
003 * you may not use this file except in compliance with the License.
004 * You may obtain a copy of the License at
005 *
006 * http://www.apache.org/licenses/LICENSE-2.0
007 *
008 * Unless required by applicable law or agreed to in writing, software
009 * distributed under the License is distributed on an "AS IS" BASIS,
010 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
011 * See the License for the specific language governing permissions and
012 * limitations under the License.
013 */
014
015package com.google.j2objc.annotations;
016
017import java.lang.annotation.ElementType;
018import java.lang.annotation.Retention;
019import java.lang.annotation.RetentionPolicy;
020import java.lang.annotation.Target;
021
022/**
023 * PLEASE READ THIS DOCUMENTATION BEFORE USING THIS ANNOTATION!
024 *
025 * <p>Note the criteria listed below which cannot be enforced by static analysis
026 * in j2objc. Prefer using {@link Weak} over @RetainedWith if possible.
027 *
028 * <p>Indicates that the annotated field (child) forms a direct reference cycle
029 * with the referring object (parent). Adding this annotation informs J2ObjC of
030 * the reference cycle between the pair of objects allowing both objects to be
031 * deallocated once there are no external references to either object.
032 *
033 * <p>{@literal @}RetainedWith can be applied when a parent object pairs itself
034 * with a child object and cannot fully manage the child's lifecycle, usually
035 * because the child is returned to the caller. It can also be applied when the
036 * child has the same class as the parent, for example on an inverse field of an
037 * invertible collection type.
038 *
039 * <p>{@literal @}RetainedWith can only be applied where there is a two-object
040 * pair with a cycle created by one reference from each object. Note: the two
041 * references can be from the same declared field. When the references are from
042 * different fields only one field should be given a @RetainedWith annotation,
043 * and the {@literal @}RetainedWith field should point from parent to child.
044 *
045 * <p>When applied carefully in the right circumstance this annotation is very
046 * useful in preventing leaks from certain Java collection types without needing
047 * to alter their behavior.
048 *
049 * <p>The following criteria must be adhered to otherwise behavior will be
050 * undefined:
051 * <ul>
052 * <li> The child object must not reassign any references back to the parent
053 *   object. Preferably references from child to parent are declared final.
054 * <li> The child object must not contain any {@link Weak} references back to the
055 *   parent object.
056 * <li> The child object must not be available to other threads at the time of
057 *   assignment. (Normally, the cycle is created upon construction of the child)
058 * </ul>
059 *
060 * @author Keith Stanger
061 */
062@Target({ ElementType.FIELD })
063@Retention(RetentionPolicy.SOURCE)
064public @interface RetainedWith {
065}