RE: ASYN R4.10 Release

[Eric Norum <norume@aps.anl.gov>]

First, an explanation of how things got to where they now are.

The asynOctet methods were developed before ability to interpose  
interfaces was part of ASYN.    It was envisioned that asynOctet would  
provide two flavours of I/O methods.  The first flavour consisted of  
the 'raw' methods (readRaw and writeRaw) which were to provide  
transparent transport of octets -- a 'byte pipe'.  The second was the  
other methods (read and write -- which I refer to as 'cooked' to  
distinguish them from 'raw')  which were to provide end-of-line  
character handling.

As ASYN continued to be developed the ability to interpose interfaces  
was added.  This provided a very flexible approach to things like  
network packet header processing.   It was apparent that interposing  
an end-of-line processing layer could neatly handle end-of-line  
processing in a driver-independent way.   This simplified low-level  
drivers since they had only to provide simple byte-pipe data transport.

The development of the asynInterposeEos layer did raise an issue,  
though.  The legacy asynOctet API still provided two input and two  
output methods.  This was confusing even for experienced developers.   
The decision was made to cut the asynOctet structure down to a single  
method for input and a single method for output.  Low-level drivers  
would provide byte-pipe transport.  Interposed layers would handle  
things like end-of-line processing, network header encapsulation,  
escape-character stuffing and other such operations.   To retain  
flexibility, an interposed layer could provide a mechanism for  
bypassing its operation and allowing transport directly to or from the  
next layer down.   The release notes show an example of this for the  
asynInterposeEos layer.   An example of code which switches between  
end-of-line processing and transparent transport is the  
readArbitraryBlockProgramData routine in asyn/devGpib/devSupportGpib.c.

It was felt that the short-term discomfort caused by changing the  
asynOctet structure was better than enduring the chronic pain from  
propagating a confusing API.  In many cases adapting to the change is  
a matter of renaming some calls and removing some dead code.  With a  
little care the resulting code can work with both old and new versions  
of the asynOctet structure.


Here's what Marty Kraimer had to add to this:
> I agree that incompatible changes to interfaces should not  done  
> lightly but if an interface has really bad or unnecessary and  
> confusing features then they should be changed. If no incompatible  
> changes are ever made the end result is often really ugly and  
> bloated code.



= 
= 
= 
========================================================================
In response to the individual points in Nick's earlier message.

> Are you suggesting:
> 1. Don't ever do structure initialisation of asyn**** interface types.
> Instead either start with a null interface, or one copied from another
> underlying interface of the same type, and only assign the methods you
> want to add or change. If you only support C99, you can do
> initialisation by member assignment.

Yes, if you want to keep the structure initializers then you must either
- Maintain code along two branches
or
- Add conditionals

If you change the code to use explicit assignments you can use the  
code with both old and new versions of ASYN.

> 2. In this case, interpose the protocol headers at the asynOctet  
> layer,
> and assign, not initialise new read and write routines. I am not  
> certain
> where the fiddling with non-standard terminators should go -  
> possibly in
> the same routine or as an interpose in asynInterposeEos.

Perhaps things are not as bad as you think.
Although you now have both 'cooked' readIt/writeIt and 'raw' readRaw/ 
writeRaw methods implemented in pmacAsynIPPort.c it appears that you  
are not actually using both -- at least not in the code in tpmac3-5.zip.

The code in pmacAsynMotor.c uses the asynSyncIO routines (writeRead,  
in particular) to perform I/O.  All this code can remain the same.
Since you were/are using only asynSyncIO->writeRead it means that you  
were/are using only the readIt and writeIt methods in pmacAsynIPPort.c.
The  readRaw and writeRaw methods in pmacAsynIPPort.c can be removed  
-- they're never used.
You must then decide which of the three approaches mentioned above to  
set up the asynOctet structure.

--
Eric Norum <norume@aps.anl.gov>
Advanced Photon Source
Argonne National Laboratory
(630) 252-4793