001/** 002 * Copyright (c) 2008-2009 Apple Inc. All rights reserved. 003 * Copyright (C) 2009-2010, Progress Software Corporation and/or its 004 * subsidiaries or affiliates. All rights reserved. 005 006 * Licensed under the Apache License, Version 2.0 (the "License"); 007 * you may not use this file except in compliance with the License. 008 * You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, software 013 * distributed under the License is distributed on an "AS IS" BASIS, 014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018package org.fusesource.hawtdispatch; 019 020/** 021 * <p> 022 * Implemented by dispatch objects which use a reference counted life cycle. 023 * </p><p> 024 * Dispatch objects start with a retained count of one. Retaining the object increments the retain counter, 025 * releasing, decrements the counter. When the counter reaches zero, the object should 026 * not longer be accessed as it will release any resources it needs to perform normal 027 * processing. 028 * </p> 029 * 030 * @author <a href="http://hiramchirino.com">Hiram Chirino</a> 031 */ 032public interface Retained { 033 034 /** 035 * <p> 036 * Increment the reference count of this object. 037 * </p> 038 * 039 * Calls to {@link #retain()} must be balanced with calls to 040 * {@link #release()}. 041 */ 042 public void retain(); 043 044 /** 045 * <p> 046 * Decrement the reference count of this object. 047 * </p><p> 048 * An object is asynchronously disposed once all references are 049 * released. Using a disposed object will cause undefined errors. 050 * The system does not guarantee that a given client is the last or 051 * only reference to a given object. 052 * </p> 053 */ 054 public void release(); 055 056 /** 057 * @return the retained counter 058 */ 059 public int retained(); 060 061 062 /** 063 * <p> 064 * Adds a disposer runnable that is executed once the object is disposed. 065 * </p><p> 066 * A dispatch object's disposer runnable will be invoked on the object's target queue 067 * once the object's retain counter reaches zero. This disposer may be 068 * used by the application to release any resources associated with the object. 069 * </p> 070 * 071 * @param disposer 072 */ 073// public void setDisposer(Runnable disposer); 074 075}