[M3devel] naming conventions for split/composed interfaces?

[Tony Hosking]

Generally, what I try to do is to make Uxxxxx.i3 files for every  
corresponding C xxxx.h file.  This way, as the C headers change it is  
easy to figure out where things should go.  Why do you need a platform- 
specific name at all?  Simply put it into a platform-specific  
subdirectory which will then be selectively included by the parent  
m3makefile.  That way, we retain a consistent name for the files  
containing relevant declarations *across* platforms.  Remember, only  
one of these subdirectories gets included in any given build (these  
are part of the run-time).  So, for simplicity's sake I would argue  
that you are once more making unneeded complexity where simplicity is  
needed.

So, simply having a "linux-generic"  directory, and "linux-amd64" +  
"linux-ppc" + "linux-x86" subdirectories, each with "Upthread",   
"Ustat", etc. should work just fine.  What's the point in making it  
more complicated?

On Apr 23, 2008, at 11:20 AM, Jay wrote:

>
> So I'm fixing AMD64_LINUX Utypes.i3, Ustat.i3, etc.
>
> Look at what I did for example with Upthread.i3 vs.  
> UpthreadMachine.i3.
>
> Ustat.i3 shall be mostly the same between PPC_LINUX, LINUXLIBC6  
> (I386_LINUX), AMD64_LINUX, etc.
>
> However struct_stat will not likely be. It appears, though I have to  
> double check, the difference cannot be abstracted out to pointer- 
> sized integer types, that the fields are of varying orders.
>
> So I want to say:
>
> linux-i386/UstatPlatformSpecific.i3
>  TYPE struct_stat = ...
>
> linux-amd64/UstatPlatformSpecific.i3
>  TYPE struct_stat = ...
>
> linux-ppc/UstatPlatformSpecific.i3
>  TYPE struct_stat = ...
>
> linuxlibc/Ustat.i3
>  TYPE struct_stat = UstatsPlatformSpecific.struct_stat;
>
> My question is simply:
>
> What is the, or a good, naming convention for UstatPlatformSpecific?
>
> Note that it /could/ be that all but x86 have the same definition,  
> so "PlatformSpecific", might be too, um, specific.
> UstatMachine? (Similarly wrong, but maybe no matter, and shorter.)
> UstatNotCommon? Sounds dumb.
> UstatX? Not as bad as it sounds. There is a precedent. It self- 
> documents the idea that there isn't an obvious good name.
> UstatInternal? UstatPrivate?
>  It's not really about hiding, so much as implementation factoring.  
> But implementation structure is an internal detail.
> UstatF? (Friend?)
> Ustructstat? no -- ideally, anything in existing Ustat.i3 that  
> varies goess here, not necessarily just this type.
>
> I do not want fork entire files.
> The system is composed of common and uncommon pieces.
> I believe the decision where to split should be in general pushed  
> down.
> However not without judgement calls.
> You know, there are things that must be shared, things that are nice  
> to share, things that are more efficient to share, things that  
> cannot be shared.
> Type declarations are usually "must" but in this case largely  
> "nice" (not Ustat, but e.g. Upthreads), and some parts of them  
> "cannot".
>
> This split/compose pattern, you know, is a way to get something like  
> #ifdef, without any language change or such.
> It does make existing code harder to read, because it is broken up  
> into more pieces, but code will always be broken up into pieces and  
> never all in one place and always require some assumption or  
> tracking down of what the next level down does (until you get to  
> atoms, quantum physics, and all that), the thing is merely to decide  
> on just what amount is the right amount (says Goldilocks.)
>
> - Jay