From ed11af9855275aff1e0fcb6c1148c3703be0a900 Mon Sep 17 00:00:00 2001 From: Jakob Odersky Date: Thu, 11 Jul 2013 17:45:22 +0200 Subject: add documentation --- .../scala/com/github/jodersky/flow/Serial.scala | 69 +++++++++++++++++++--- .../com/github/jodersky/flow/SerialManager.scala | 2 +- .../com/github/jodersky/flow/SerialOperator.scala | 4 +- .../jodersky/flow/internal/InternalSerial.scala | 18 +++--- 4 files changed, 74 insertions(+), 19 deletions(-) diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala b/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala index bff0ad0..adcfb06 100644 --- a/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala +++ b/flow-main/src/main/scala/com/github/jodersky/flow/Serial.scala @@ -7,19 +7,72 @@ import akka.util.ByteString /** Defines messages used by serial IO layer. */ object Serial extends ExtensionKey[SerialExt] { + /** A message extending this trait is to be viewed as a command, that is an outbound message. */ trait Command + + /** A message extending this trait is to be viewed as an event, that is an inbound message. */ trait Event - + + /** + * Open a new serial port. Send this command to the serial manager to request the opening of a new port. + * @param handler actor that will receive events from the specified serial port + * @param port name of serial port + * @param baud baud rate to use with serial port + * @param characterSize size of a character of the data sent through the serial port + * @param twoStopBits set to use two stop bits instead of one + * @param parity type of parity to use with serial port + */ case class Open(handler: ActorRef, port: String, baud: Int, characterSize: Int = 8, twoStopBits: Boolean = false, parity: Parity.Parity = Parity.None) extends Command - case class Opened(port: String) extends Event - case class OpenFailed(port: String, reason: Throwable) extends Event - + + /** + * Event sent from a port operator, indicating that a serial port was successfully opened. + * @param port name of serial port + * @param baud baud rate to use with serial port + * @param characterSize size of a character of the data sent through the serial port + * @param twoStopBits set to use two stop bits instead of one + * @param parity type of parity to use with serial port + */ + case class Opened(port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Parity.Parity) extends Event + + /** + * Event sent from manager, indicating that a serial port could not be opened. + * @param reason throwable containing reason to why the requested port could not be opened + * @param port name of serial port + * @param baud baud rate to use with serial port + * @param characterSize size of a character of the data sent through the serial port + * @param twoStopBits set to use two stop bits instead of one + * @param parity type of parity to use with serial port + */ + case class OpenFailed(reason: Throwable, port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Parity.Parity) extends Event + + /** + * Event sent by operator, indicating that data was received from the operator's serial port. + * @param data data received by port + */ case class Received(data: ByteString) extends Event - + + /** + * Command sent to operator, requesting the writing of data to the operator's serial port. Optionally request acknowledgment when data is written. + * @param data data to be written to port + * @param ack set to true to receive acknowledgment on successful write + * @see Wrote + */ case class Write(data: ByteString, ack: Boolean = false) extends Command + + /** + * Event sent by operator, acknowledging that data was written to its serial port. Note that such an acknowledgment only guarantees that data has been written + * to the serial port's output buffer (managed by the operating system), the actual reception of the data on the remote device is not guaranteed. + * @param data the data that has been written + */ case class Wrote(data: ByteString) extends Event - + + /** Command sent to operator to request the closing of its serial port. */ case object Close extends Command - case class Closed(error: Option[Exception]) extends Event - + + /** + * Event sent from operator, indicating that its port has been closed. An optional reason explains the error that caused the closing of the port. + * @param reason Some(exception) explaining the exception that caused the closing, None if the port was closed by sending a `Close` message. + */ + case class Closed(reason: Option[Exception]) extends Event + } diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala b/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala index 1a38ef5..1f32ecd 100644 --- a/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala +++ b/flow-main/src/main/scala/com/github/jodersky/flow/SerialManager.scala @@ -32,7 +32,7 @@ class SerialManager extends Actor with ActorLogging { case Open(handler, port, baud, cs, tsb, parity) => Try { InternalSerial.open(port, baud, cs, tsb, parity.id) } match { case Failure(t) => { log.debug(s"failed to open low serial port at ${port}, baud ${baud}, reason: " + t.getMessage()) - handler ! OpenFailed(port, t) + handler ! OpenFailed(t, port, baud, cs, tsb, parity) } case Success(serial) => { diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala b/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala index 604dc74..4e46343 100644 --- a/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala +++ b/flow-main/src/main/scala/com/github/jodersky/flow/SerialOperator.scala @@ -50,16 +50,14 @@ class SerialOperator(handler: ActorRef, serial: InternalSerial) extends Actor wi override def run() { this.setName("flow-reader " + serial.port) - log.debug(name + ": started reader thread") enterReadLoop() - log.debug(name + ": exiting") } } override def preStart() = { context watch handler - handler ! Opened(serial.port) + handler ! Opened(serial.port, serial.baud, serial.characterSize, serial.twoStopBits, Parity(serial.parity)) Reader.start() } diff --git a/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala b/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala index fd5aaa4..c7752b2 100644 --- a/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala +++ b/flow-main/src/main/scala/com/github/jodersky/flow/internal/InternalSerial.scala @@ -5,13 +5,13 @@ import com.github.jodersky.flow._ import java.util.concurrent.atomic.AtomicBoolean /** Wraps NativeSerial in a more object-oriented style, still quite low level. */ -class InternalSerial private (val port: String, private val pointer: Long) { +class InternalSerial private (val port: String, val baud: Int, val characterSize: Int, val twoStopBits: Boolean, val parity: Int, private val pointer: Long) { import InternalSerial._ private val reading = new AtomicBoolean(false) private val writing = new AtomicBoolean(false) private val closed = new AtomicBoolean(false) - + /** Closes the underlying serial connection. Any threads blocking on read or write will return. */ def close(): Unit = synchronized { if (!closed.get()) { @@ -23,8 +23,10 @@ class InternalSerial private (val port: String, private val pointer: Long) { } } - /** Read data from underlying serial connection. - * @throws PortInterruptedException if port is closed from another thread */ + /** + * Read data from underlying serial connection. + * @throws PortInterruptedException if port is closed from another thread + */ def read(): Array[Byte] = if (!closed.get) { reading.set(true) try { @@ -41,8 +43,10 @@ class InternalSerial private (val port: String, private val pointer: Long) { throw new PortClosedException(s"port ${port} is already closed") } - /** Write data to underlying serial connection. - * @throws PortInterruptedException if port is closed from another thread */ + /** + * Write data to underlying serial connection. + * @throws PortInterruptedException if port is closed from another thread + */ def write(data: Array[Byte]): Array[Byte] = if (!closed.get) { writing.set(true) try { @@ -79,7 +83,7 @@ object InternalSerial { def open(port: String, baud: Int, characterSize: Int, twoStopBits: Boolean, parity: Int): InternalSerial = synchronized { val pointer = new Array[Long](1) except(NativeSerial.open(port, baud, characterSize, twoStopBits, parity, pointer), port) - new InternalSerial(port, pointer(0)) + new InternalSerial(port, baud, characterSize, twoStopBits, parity, pointer(0)) } /** Set debugging for all serial connections. Debugging results in printing extra messages (from the native library) in case of errors. */ -- cgit v1.2.3