[Rxtx] to flush or not to flush, that is a question

[Dr. Douglas Lyon]

Hi All,
Please note the following javadoc on the close method
in the CommPortInterface.
Should it be modified to mention the flush?
The goal is to provide a abstract specification that we
can implement on multiple platforms, as Trent suggests.
Thanks!
  - Doug

P.S. IMHO, an automatic flush could be an option, like
on the PrintStream.

autoFlush - A boolean; if true, the output buffer will be flushed 
whenever a byte array is written,
the close method is invoked, or a newline character or byte ('\n') is written.

In the world of real-time control, autoFlush may be important.

Here is what I have so far:

public interface CommPortInterface {
     /**
      * @return the name of this port.
      */
     String getName();

     /**
      * @return a string representation of this port.
      */
     String toString();

     /**
      * Closes this communications port. Further methods on this object will
      * throw IllegalStateException. All PortOwnershipListeners will be
      * notified of this change of ownership.
      */
     void close();
}

>On Fri, 29 Sep 2006, Dr. Douglas Lyon wrote:
>
>>  Hi All,
>>  Let me see if I can summarize the discussion on flushing so far:
>>
>>  1. Manual Flush: A close is just a close vs.
>>  2. Automatic Flush: A close is a flush and then a close.
>>
>>  On the one hand we can define a close for a serial port
>>  so that it closes the serial port and has no other role. If
>>  data has been left in the buffer, it will be lost unless a flush
>>  is done explicitly.
>>
>>  While it is the case that this would seem to speed up
>>  the close method, some might argue that the loss of data is
>>  not good software engineering, thus impacting system reliability.
>>  People will use:
>>  sp.flush();
>>  sp.close();
>>  as a serial port idiom, if close does not automatically flush.
>>
>>  If flush does not precede close,
>>  the possible loss of data should be taken into
>>  account at the programmers' level, or it is a semantic error.
>>
>>  Others argue that a slow serial line will delay the delivery of
>>  data for so long that the close will appear stalled.
>>
>>  Corner-point: The emperor has no close.
>>
>>  Suppose the serial device gets all stuffed up and data
>>  cannot be delivered. In such a case, the close will never
>>  finish with the flush and the serial port will never be released.
>>
>>  In such a case, other programs (and users) who need the resource
>>  will be unable to access it.
>>
>>  Digression: once I went to a wedding on a boat where the head
>>  was all stuffed up. Users were unable to flush and the
>>  OutputStream never closed... :(
>>
>>  A serial port is a system wide resource for which many applications
>>  may contend. Once it is assigned to a process, in theory, no other
>>  application may usurp it.
>>
>>  Wont deadlock from unreleased resources impact system reliability?
>>
>>  So, on the one hand we adversely impact system reliability with
>>  increased chance of deadlock, or adversely impact system reliability
>>  with increased chance of data loss.
>>
>>  To address the corner-point, the flush might need a time-out. Perhaps
>>  this can be computed as a function of the serial port data rate and the
>>  amount of data in the buffer.
>>
>>  Please let me know if I am missing something.
>>
>
>output buffer empty events are flushes on Solaris and some other Unix
>Systems for all practical purposes.  Every write has a flush on those
>systems as that is the only means of knowing when to send the event.
>
>Any Java API should abstract these details away from the programmer and
>behave the same on all systems.
>
>--
>Trent Jarvi
>tjarvi at qbang.org
>_______________________________________________
>Rxtx mailing list
>Rxtx at qbang.org
>http://mailman.qbang.org/mailman/listinfo/rxtx