Experimental Physics and
Industrial Control System

Hi,

Perhaps we can adopt a process where we depreciate API functions that
should not be used? Any accompanying documentation can mark the
function/method as depreciated (for example, by using the @deprecated
tag in some code documentation tools) and explain why it is depreciated
and suggest alternatives.

Then developers have some time to modify existing code before the
depreciated functions are finally removed in a subsequent release.

Cheers,
Matthew
DLS Controls

-----Original Message-----
From: [email protected] [mailto:[email protected]] On Behalf Of Eric Norum
Sent: 25 September 2008 16:51
To: Rees, NP (Nick)
Cc: epics Techtalk
Subject: RE: ASYN R4.10 Release

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 <[email protected]>
Advanced Photon Source
Argonne National Laboratory
(630) 252-4793

<DIV><FONT size="1" color="gray">This e-mail and any attachments may contain confidential, copyright and or privileged material, and are for the use of the intended addressee only. If you are not the intended addressee or an authorised recipient of the addressee please notify us of receipt by returning the e-mail and do not use, copy, retain, distribute or disclose the information in or attached to the e-mail.
Any opinions expressed within this e-mail are those of the individual and not necessarily of Diamond Light Source Ltd. Diamond Light Source Ltd. cannot guarantee that this e-mail or any attachments are free from viruses and we cannot accept liability for any damage which you may sustain as a result of software viruses which may be transmitted in or with the message.
Diamond Light Source Limited (company no. 4375679). Registered in England and Wales with its registered office at Diamond House, Harwell Science and Innovation Campus, Didcot, Oxfordshire, OX11 0DE, United Kingdom
</FONT></DIV>

--
Dr. Dirk Zimoch
Paul Scherrer Institut, WBGB/006
5232 Villigen PSI, Switzerland
Phone +41 56 310 5182

Replies:

Re: ASYN R4.10 Release - code depreciation Andrew Johnson

References:

RE: ASYN R4.10 Release Eric Norum

RE: ASYN R4.10 Release - code depreciation Pearson, MR (Matthew)

Navigate by Date:

Prev: Re: SIemens PLCs Matthias Clausen

Next: Re: EDM font sizes Kevin Anderson

Index: 1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  <2008>  2009  2010  2011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024 

Navigate by Thread:

Prev: RE: ASYN R4.10 Release - code depreciation Pearson, MR (Matthew)

Next: Re: ASYN R4.10 Release - code depreciation Andrew Johnson

Index: 1994  1995  1996  1997  1998  1999  2000  2001  2002  2003  2004  2005  2006  2007  <2008>  2009  2010  2011  2012  2013  2014  2015  2016  2017  2018  2019  2020  2021  2022  2023  2024