Oracle Coherence for C++ API
Release 3.7.0.0

E18684-01

coherence/util/Queue.hpp

00001 /*
00002 * Queue.hpp
00003 *
00004 * Copyright (c) 2000, 2011, 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
Copyright © 2000, 2011, Oracle and/or its affiliates. All rights reserved.