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