Menu
▾
▴
[Jnode-svn-commits] SF.net SVN: jnode:[5140] trunk
|
From: <cr...@us...> - 2009-03-22 02:02:12
|
Revision: 5140
http://jnode.svn.sourceforge.net/jnode/?rev=5140&view=rev
Author: crawley
Date: 2009-03-22 02:02:07 +0000 (Sun, 22 Mar 2009)
Log Message:
-----------
Javadocs and FIXMEs
Modified Paths:
--------------
trunk/core/src/core/org/jnode/util/AccessControllerUtils.java
trunk/core/src/core/org/jnode/util/BooleanUtils.java
trunk/core/src/core/org/jnode/util/ByteBufferInputStream.java
trunk/core/src/core/org/jnode/util/ByteQueue.java
trunk/gui/src/driver/org/jnode/driver/ps2/PS2ByteChannel.java
trunk/gui/src/driver/org/jnode/driver/ps2/PS2Driver.java
Modified: trunk/core/src/core/org/jnode/util/AccessControllerUtils.java
===================================================================
--- trunk/core/src/core/org/jnode/util/AccessControllerUtils.java 2009-03-21 14:59:56 UTC (rev 5139)
+++ trunk/core/src/core/org/jnode/util/AccessControllerUtils.java 2009-03-22 02:02:07 UTC (rev 5140)
@@ -33,8 +33,8 @@
* Calls AccessController.doPrivileged and unwraps any exception wrapped
* in the PrivilegedActionException.
*
- * @param action
- * @return
+ * @param action a typed action
+ * @return an instance of the action's type.
* @throws Exception
*/
public static <T> T doPrivileged(PrivilegedExceptionAction<T> action) throws Exception {
Modified: trunk/core/src/core/org/jnode/util/BooleanUtils.java
===================================================================
--- trunk/core/src/core/org/jnode/util/BooleanUtils.java 2009-03-21 14:59:56 UTC (rev 5139)
+++ trunk/core/src/core/org/jnode/util/BooleanUtils.java 2009-03-22 02:02:07 UTC (rev 5140)
@@ -26,10 +26,11 @@
public class BooleanUtils {
/**
- * Returns true if value equals "true", "on", "yes" or "1".
+ * Returns {@code true} if value equals "true", "on", "yes" or "1".
*
- * @param value Can be null
- * @return
+ * @param value A string value to be interpreted as a boolean, or {@code null}
+ * which will be mapped to {@code false}.
+ * @return the value's boolean interpretation.
*/
public static boolean valueOf(String value) {
if (value == null) {
Modified: trunk/core/src/core/org/jnode/util/ByteBufferInputStream.java
===================================================================
--- trunk/core/src/core/org/jnode/util/ByteBufferInputStream.java 2009-03-21 14:59:56 UTC (rev 5139)
+++ trunk/core/src/core/org/jnode/util/ByteBufferInputStream.java 2009-03-22 02:02:07 UTC (rev 5140)
@@ -24,6 +24,10 @@
import java.io.InputStream;
import java.nio.ByteBuffer;
+/**
+ * @author epr
+ * @author Andrei DORE
+ */
public class ByteBufferInputStream extends InputStream {
private final ByteBuffer buf;
@@ -31,10 +35,7 @@
this.buf = buf;
}
- /**
- * @Override
- * @see java.io.InputStream#read()
- */
+ @Override
public int read() throws IOException {
if (buf.remaining() > 0) {
return buf.get() & 0xFF;
@@ -44,9 +45,6 @@
}
@Override
- /**
- * @author Andrei DORE
- */
public int available() throws IOException {
return buf.remaining();
}
Modified: trunk/core/src/core/org/jnode/util/ByteQueue.java
===================================================================
--- trunk/core/src/core/org/jnode/util/ByteQueue.java 2009-03-21 14:59:56 UTC (rev 5139)
+++ trunk/core/src/core/org/jnode/util/ByteQueue.java 2009-03-22 02:02:07 UTC (rev 5140)
@@ -21,14 +21,20 @@
package org.jnode.util;
/**
- * ByteQueue.java
- * <p/>
- * a simple fixed-length Queue.
+ * A simple fixed-length Queue for buffering bytes. This queue is designed to
+ * never block on the input side. If the queue is full when 'push' is called,
+ * a byte will be discarded from the head of the queue to make space at the
+ * tail for the new byte.
*
* @author epr
*/
public class ByteQueue {
-
+ // FIXME ... Looking at the way this class is used, I think it may needs an
+ // atomic drain operation and/or a close operation.
+
+ /**
+ * The default queue size.
+ */
static final int Q_SIZE = 10;
private final byte[] data;
@@ -36,15 +42,28 @@
private int top = 0;
private int bottom = 0;
+ /**
+ * Create a queue with the default size.
+ */
public ByteQueue() {
this(Q_SIZE);
}
+ /**
+ * Create a queue with the supplied size.
+ * @param size the queue size in bytes; should be >= 1.
+ */
public ByteQueue(int size) {
this.data = new byte[size + 1];
this.size = size;
}
+ /**
+ * Add a byte at the tail of the queue. This method does not block.
+ * If the queue is full when 'push' is called, space for the byte is
+ * made by removing (and discarding) the byte at the head of the queue.
+ * @param o the byte to be added to the queue.
+ */
public synchronized void push(byte o) {
data[bottom] = o;
bottom++;
@@ -60,12 +79,20 @@
notifyAll();
}
+ /**
+ * Remove a byte from the head of the queue, blocking until one becomes
+ * available. If the thread calling this method is interrupted while waiting
+ * for data, the method returns a zero byte.
+ *
+ * @return the byte removed, or zero if the method call was interrupted.
+ */
public synchronized byte pop() {
while (top == bottom) { /* Q is empty */
try {
wait();
} catch (InterruptedException ie) {
- // TODO: better throw a NoSuchElementException or alike!!!
+ // FIXME ... this approach to handling interrupts is broken. The
+ // exception should be allowed to propagate
return 0;
}
} /* wait for push to fill Q */
@@ -79,6 +106,17 @@
return r;
}
+ /**
+ * Remove a byte from the head of the queue, blocking with a timeout if data is
+ * not immediately available. Unlike {@link #pop()}, this method does <b>not</b>
+ * return zero when interrupted!
+ *
+ * @param timeout the maximum time (in milliseconds) to wait for data to become
+ * available. If zero, the method will wait as long as necessary.
+ * @return the byte removed from the queue.
+ * @throw InterruptedException if the method call is interrupted.
+ * @throw TimeoutException if no data is available within the required time.
+ */
public synchronized byte pop(long timeout)
throws TimeoutException, InterruptedException {
while (top == bottom) { /* Q is empty */
@@ -98,13 +136,16 @@
}
/**
- * Wait until there is data in the queue and return the first
- * element, without removing it.
+ * Return the byte at the head of the queue without removing it. If data is
+ * not immediately available, the method will block (with a timeout) until
+ * data is available. Unlike {@link #pop()}, this method does <b>not</b>
+ * return zero when interrupted!
*
- * @param timeout
- * @return
- * @throws TimeoutException
- * @throws InterruptedException
+ * @param timeout the maximum time (in milliseconds) to wait for data to become
+ * available. If zero, the method will wait as long as necessary.
+ * @return the byte removed from the queue.
+ * @throw InterruptedException if the method call is interrupted.
+ * @throw TimeoutException if no data is available within the required time.
*/
public synchronized byte peek(long timeout)
throws TimeoutException, InterruptedException {
@@ -117,7 +158,13 @@
return data[top];
}
+ /**
+ * Test if there is no data in the queue.
+ * @return {@code true} if the queue is empty, {@code false} otherwise.
+ */
public boolean isEmpty() {
+ // FIXME ... this should be synchronized.
return (top == bottom);
}
+
}
Modified: trunk/gui/src/driver/org/jnode/driver/ps2/PS2ByteChannel.java
===================================================================
--- trunk/gui/src/driver/org/jnode/driver/ps2/PS2ByteChannel.java 2009-03-21 14:59:56 UTC (rev 5139)
+++ trunk/gui/src/driver/org/jnode/driver/ps2/PS2ByteChannel.java 2009-03-22 02:02:07 UTC (rev 5140)
@@ -55,7 +55,7 @@
throw new ClosedChannelException();
}
- // ToDo: proper exception handling (if end of queue -> IOException)
+ // FIXME: proper exception handling (if end of queue -> IOException)
int i;
for (i = 0; i < dst.remaining(); i++) {
dst.put(queue.pop());
@@ -116,6 +116,8 @@
* Remove all data from this channel
*/
public void clear() {
+ // FIXME ... there is synchronization issues here. The 'isEmpty' method
+ // is not synchronized, so we may not see the real state of the queue.
while (!queue.isEmpty()) {
queue.pop();
}
Modified: trunk/gui/src/driver/org/jnode/driver/ps2/PS2Driver.java
===================================================================
--- trunk/gui/src/driver/org/jnode/driver/ps2/PS2Driver.java 2009-03-21 14:59:56 UTC (rev 5139)
+++ trunk/gui/src/driver/org/jnode/driver/ps2/PS2Driver.java 2009-03-22 02:02:07 UTC (rev 5140)
@@ -59,11 +59,8 @@
*/
protected synchronized void startDevice() throws DriverException {
init();
- getDevice().registerAPI(CharacterDeviceAPI.class, this); // make sure
- // it's at
- // least a
- // character
- // device
+ // Make sure it's at least a character device
+ getDevice().registerAPI(CharacterDeviceAPI.class, this);
}
/**
@@ -89,7 +86,7 @@
throw new ClosedChannelException();
}
- // ToDo: proper exception handling (if end of queue -> IOException)
+ // FIXME: proper exception handling (if end of queue -> IOException)
int i;
for (i = 0; i < dst.remaining(); i++) {
dst.put(queue.pop());
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|
