32 bit file handles. Was: Font_ApplyFields problem

[Tony van der Hoff]

On 7 Nov 2001, in message <3BE9106B.10423.27ECC0 at localhost>,
"Jonathan Coxhead" <jonathan at doves.demon.co.uk> wrote:

> > >    Suppose osfile.swi contained "NEEDS osfile32", and we supply a
> > > header  osfile32.h as follows:
> > > 
> > >       #ifndef osfile32_H
> > >       #define osfile32_H
> > > 
> > >       #if !defined OSLIB_F8
> > >       #define os_f                 os_fw
> > >       #define xosfile_save_stamped xosfile_save_stamped_w
> > >       #define osfile_save_stamped  osfile_save_stamped_w
> > >       #endif
> > > 
> > >       #endif
> > > 
> 
>    The basic requirement of any solution is that headers can never be
> allowed  to include themselves, either directly or indirectly. The way the
> C type system  works, you can get away with this sometimes; but it's a very
> bad idea. I read  an excellent book on software (Lakos,
> _Large_Scale_C++_Software_Design_) which  makes this point well.
> 
>    In abstract terms, this means that if you write a directed graph, where
> the  "nodes" are the headers and the "arcs" point from a file to everything
> it  includes, the graph must be acyclic.
> 
OK, I understand the theory, and am in complete agreement with your
reasoning. I have no problem with your suggestion, but I don't think I'm
contravening that requirement, and am only seeking clarification.
 
>    If we have a single "osf32.h" that is automatically included by OSLib 
> headers, we can get the following
> 
>       os.h includes osf32.h
>       osf32.h includes osfile.h
>       osfile.h includes os.h
> 
Only if osf32.h includes osfile.h; I see no reason why it should. Even if it
did, the #ifndef OSF32_H would protect against its multiple inclusion (OK,
strictly, this would be in contravention of your requirement for an acyclic
directed graph, but then it's only a belt-and-braces catch-all. Are you
implying that there is no need for this protection?).

>    But if each header xxx.h has its own associated xxx32.h, which it drags
> in  automatically (but doesn't include anything else) then the formal
> problem goes  away.
> 
Maybe I'm missing something, but I don't understand how having multiple
headers is at all pertinent to the situation: if xxx32.h has no need to
include something else, then neither does osf32.h. 

Also, I must ask again: where do you propose placing the common definition
"#define os-f os_fw"? In all of 'em or in one central place, which is itself
#included? Would this not be osf32.h?

>    This also has the benefit that when someone introduces a new header,
> which  may need os_f/os_fw switching (assuming they want to do it like
> that), there is  no central "repository" file that must be updated: they
> just create their own,  independently of the rest of the system. This
> matches the OSLib design, where  message numbers, error numbers, etc, are
> defined by the modules that export  them, not in a central place.
> 
Indeed, this is a benefit, and justifies your scheme; I'm happy to go with
it.

>    I guess the "new way" of writing a SWI definition would be write only
> the  version with os_fw (but giving it a name with no _w suffix), and
> ignore os_f  completely.
> 
Well, there's an interesting point, to which I hadn't previously given much
thought. 

I agree that 8-bit handles should be considered obsolete, and ideally we
shouldn't have to write any new functions to support their use, but I don't
think we should abandon the _w functions. They provide the user with a
guarantee that 32-bit handles will be used, regardless of any compile-time
switches, and thus provide better type-safety. Furthermore, if someone, in a
project, has used _w functions throughout, it may be more intuitive to
continue doing so; I think I personally would. 

One day, (maybe when OS handles really start using more than 8 bits) we may
choose to abandon support for 8 bit handles. However, we could *never* re-use
the non-w symbols, so that the user will at least get errors when he tries to
compile or link old code. For consistency, we may as well continue to use the
_w suffix.

So, I think that the _w names will for evermore form the base symbols for
this area of the library, and we therefore need to provide the short name
equivalents in the xxx32.h files for consistency. Of course these could be
unswitched, if no 'natural' short form were available, but that would be
potentially confusing to a user who has opted for 8-bit handles (by defining
OS_F8), and expects to get an 8-bit interface.

Regrettably, I believe we are thus forced into writing both sets of functions
for the time being.



-- 
Tony van der Hoff         | MailTo:tony at mk-net.demon.co.uk
                          | MailTo:avanderhoff at iee.org
Buckinghamshire, England  | http:www.mk-net.demon.co.uk