Clarifying the Javadocs for EventQueue's getNextEvent()

Engines, Libraries and Tools JInput
#1

The standard javadocs for EventQueue show that the full API for getNextEvent() is

[quote]getNextEvent
public final boolean getNextEvent(Event event)
[/quote]
With nothing about what it actually does, what the argument is, when it returns true, etc.

I take it from the sample code that turns true when there is the queue is not empty, and when it is going to return true, it modifies the argument “event” to contain the event at the top of the queue.

If this is a correct guess, I’m more than willing to change the source to improve the javadoc.

Is this guess correct?

And if so, how to I submit a patch? or to who?

thanks
Pat

BTW, I’m not a fan of the API’s design, which is more of a C-idiom than a standard Java one. Usually in Java, you return the entry in the queue, and if its non-blocking, you would return a null.

#2

Hi

The API was designed by a group of engineers from companies like sun and sony, it’s something we could change these days if we really wanted, but that would cause issues to people upgrading. That doesn’t mean it can’t happen, just that we ought to have a good reason to do so.

The getNextEvent method returns true if the queue had an event on it, and it managed to populate the event object you passed in with the details. False if there was nothing in the queue to copy in to your event object.
Populating an object you pass in is an efficiency saving designed to reduce the number of objects created, and thus the amount of GC needed.

Best place to submit patches is here. I’ll give it a review and commit. After a few acceptable patches I’d be happy to add people to the commiters list.

HTH

Endolf

#3

Cool. What’s the proper access for read-only? I assume its all in CVS/SVN/GIT or something similar.

#4

It’s all on jinput.java.net, you can get read access and request other roles there.

HTH

Endolf

#5

new thread created for this.

#6

[quote=“endolf,post:2,topic:36234”]
Actually, this is not a correct optimization. Some lower level code (probably the poll() function) creates the Event objects and places them in the queue. There is nothing to be gained by passing in an object to populate. The standard Queue functions in the JDK just return the reference to the object created elsewhere, and “add()” to the queue.

What this class needs, IMHO, is functions aligned with the JDK’s Interface Queue, specifically the peek() and poll() functions. They are the standard way of dealing with queues.

#7

Erm, have you written or looked at that code?, the event queue creates x events (where x is the max queue size) and holds on to them and reuses them. This way, no objects are created at run time (after the initial setup).

Endolf

#8

Yes, and the add() code replaces the Event object at the tail.

Seriously, take a breath. Its OK for old code to have creaky edges.

To make a full assessment, I’d have to dive into the code that populates the queue when you do a poll(), which is more effort than this tiny routine merits. But in the AbstractController class, the poll() function calls add() on the queue, replacing the Event that was there with the static one in the class. The Event is loaded using getNextDeviceEvent(Event event), which is abstract. Other implementations may do other things.

#9

If you mean line 232 of AbstractController, and then look at what the add method is doing, it takes the values from the supplied event, and sets them on the event at the tail of the queue. It wouldn’t work if we did it with the static as every single event in the queue would end up being set to the static one.

And I’m sure there are some creaky bits in there, but you’ve yet to find those :slight_smile:

Endolf