Re: ASYN R4.10 Release - code depreciation

[Dirk Zimoch <dirk.zimoch@psi.ch>]

Hi,

The gnu compiler has an extension called attributes. One can mark a function, 
variable, or type with __attribute__((deprecated)). (For other compilers, define 
 an empty macro __attribute__(x) for compatibility.) This produces a compiler 
warning when the function or variable is used.

Dirk


Pearson, MR (Matthew) wrote:
> 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: tech-talk-bounces@aps.anl.gov 
> > [mailto:tech-talk-bounces@aps.anl.gov] 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 <norume@aps.anl.gov>
> > 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