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}