Because these methods have different semantics explained in the JavaDoc. add/remove are unconditional while offer/poll return special value:

• offer only offers a new value, but it might not be accepted, e.g. if the queue is full

• poll only polls for the value, but we accept the fact the value might not be there.

To complicate matters more, BlockingQueue introduces yet another pair of methods for blocking add/remove. Of course they could have used the same named with a bunch of parameters/flags,

smellyGet(boolean blocking, boolean failOnEmpty)

but don't you think this is a better design?

        | Throws ex. | Special v. | Blocks | Times out
--------+------------+------------+--------+---------------------
Insert  | add(e)     | offer(e)   | put(e) | offer(e, time, unit)
Remove  | remove()   | poll()     | take() | poll(time, unit)
Examine | element()  | peek()     | N/A    | N/A

^{* https://meta.stackexchange.com/questions/73566}

I am assuming that "PQ" means "priority queue". I've never used such a queue (my mental image of a queue is that of a strictly FIFO structure), but after reading documentation, I think you can do this:

First, you need to create the class of the object you want to store in the queue. Assuming int contents and int priority:

public class MyClass implements Comparable<MyClass> {
    private int x, p;

    /*
     * x: Contents
     * p: Priority
     */
    public MyClass(int x, int p) {
        this.x = x;
        this.p = p;
    }

    @override
    public int compareTo(MyClass o) {
        return this.p - o.p;
    }

    public int getX() {
        return x;
    }
}

Now, create your priority queue. If I understood correctly the class documentation, it will use the compareTo method to sort your objects:

....
PriorityQueue<MyClass> pq = new PriorityQueue<MyClass>();
....
pq.add(new MyClass(x, p));
....

Check: http://docs.oracle.com/javase/7/docs/api/java/util/PriorityQueue.html

Java queues don't have enqueue and dequeue methods; these operations are done using the following methods:

• Enqueuing:
  • add(e): throws exception if it fails to insert the object
  • offer(e): returns false if it fails to insert the object
• Dequeuing:
  • remove(): throws exception if the queue is empty
  • poll(): returns null if the queue is empty
• Take a look to the first object in the queue:
  • element(): throws exception if the queue is empty
  • peek(): returns null if the queue is empty

And now, finally: when to use offer and add?

About offer and add: Well, that depends on how do you want to handle the failure of the insertion in the queue:

The add method, which Queue inherits from Collection, inserts an element unless it would violate the queue's capacity restrictions, in which case it throws IllegalStateException. The offer method, which is intended solely for use on bounded queues, differs from add only in that it indicates failure to insert an element by returning false.

(see: http://docs.oracle.com/javase/tutorial/collections/interfaces/queue.html)

Hope this helps you

The queue module is specifically designed for inter-thread communication. Its design is not intended to facilitate single-threaded usage; for example, methods like peek don't make much sense for a thread synchronization mechanism, so queue.PriorityQueue doesn't have peek support. This is similar to how Go channels have no peek mechanism.

If you want a priority queue for reasons other than inter-thread communication, the heapq module is more appropriate. With heapq, peek is just heap[0].