00001 /* 00002 * Queue.hpp 00003 * 00004 * Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_QUEUE_HPP 00017 #define COH_QUEUE_HPP 00018 00019 #include "coherence/lang.ns" 00020 00021 #include "coherence/util/Iterator.hpp" 00022 00023 COH_OPEN_NAMESPACE2(coherence,util) 00024 00025 00026 /** 00027 * The Queue provides a means to efficiently (and in a thread-safe manner) 00028 * queue received messages and messages to be sent. 00029 * 00030 * @author nsa 2008.01.18 00031 */ 00032 class COH_EXPORT Queue 00033 : public interface_spec<Queue> 00034 { 00035 // ----- Queue interface ------------------------------------------------ 00036 00037 public: 00038 /** 00039 * Appends the specified element to the end of this queue. Queues may 00040 * place limitations on what types of elements may be added and should 00041 * clearly specify in their documentation any restrictions. 00042 * 00043 * @param oh element to be appended to this Queue 00044 * 00045 * @return true if the collection changed as a result of this call 00046 * 00047 * @throw ClassCastException if the class of the specified element 00048 * prevents it from being added to this Queue 00049 */ 00050 virtual bool add(Object::Holder oh) = 0; 00051 00052 /** 00053 * Insert the specified element to the front of this queue. Queues may 00054 * place limitations on what types of elements may be added and should 00055 * clearly specify in their documentation any restrictions. 00056 * 00057 * @param oh element ot be prepended to this Queue 00058 * 00059 * @return true if the collection changed as a result of this call 00060 * 00061 * @throw ClassCastException if the class of the specified element 00062 * prevents it from being added to this Queue 00063 */ 00064 virtual bool addHead(Object::Holder oh) = 0; 00065 00066 /** 00067 * Flush the queue. 00068 */ 00069 virtual void flush() = 0; 00070 00071 /** 00072 * Determine whether the Queue is empty or not. 00073 * 00074 * @return true if the Queue is empty; false if not 00075 */ 00076 virtual bool isEmpty() const = 0; 00077 00078 /** 00079 * Returns the first element from the front of this Queue. 00080 * 00081 * There is no blocking equivalent of this method as it would require 00082 * notification to wake up from an empty Queue, and this would mean 00083 * that the "add" and "addHead" methods would need to perform 00084 * notifyAll over notify which has performance implications. 00085 * 00086 * @return the first element in the front of this Queue or null if 00087 * the Queue is empty 00088 */ 00089 virtual Object::Holder peekNoWait() = 0; 00090 00091 /** 00092 * Waits for and removes the first element from the front of this 00093 * Queue. 00094 * 00095 * If the Queue is empty, this method will block until an element is 00096 * in the Queue. The unblocking equivalent of this method is 00097 * "removeNoWait". 00098 * 00099 * @return the first element in the front of this Queue 00100 */ 00101 virtual Object::Holder remove() = 0; 00102 00103 /** 00104 * Removes and returns the first element from the front of this Queue. 00105 * 00106 * The blocking equivalent of this method is "remove". 00107 * 00108 * @return the first element in the front of this Queue or NULL if 00109 * the Queue is empty 00110 */ 00111 virtual Object::Holder removeNoWait() = 0; 00112 00113 /** 00114 * Determine the number of elements in this Queue. The size of the 00115 * Queue may change after the size is returned from this method. 00116 * 00117 * @return the number of elements in this Queue 00118 */ 00119 virtual size32_t size() const = 0; 00120 }; 00121 00122 COH_CLOSE_NAMESPACE2 00123 00124 #endif // COH_QUEUE_HPP