Re: How to Design an Application Programmers' Interface (API)

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

"vrml3d.com" wrote:

> Why all the fuss about API design?
> 3.14159 is usually good enough,
> and, if you need more precision,
> there are plenty of places to get it.  :)

I hate jammers;-)

Re: How to Design an Application Programmers' Interface (API)

[Keith Thompson]

"Tony T. Warnock" <u091889@cic-mail.lanl.gov> writes:
[...]
> For the same number of characters one can even use 355/113.

Which evaluates to 3 in C, C++, Fortran, and Ada (the four languages
whose newsgroups this thread is gratuitously cross-posted to).

-- 
Keith Thompson (The_Other_Keith) kst@cts.com  <http://www.ghoti.net/~kst>
San Diego Supercomputer Center           <*>  <http://www.sdsc.edu/~kst>
Welcome to the last year of the 20th century.

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Keith Thompson wrote:

> Which evaluates to 3 in C, C++, Fortran, and Ada
> (the four languages whose newsgroups
>  that this thread is gratuitously cross-posted to).

Be patient Keith,

You may find what I have to say
about the GSL (GNU Scientific Library) API very interesting.
But first,
I think a critique of the BLAS (Basic Linear Algebra Subroutine)
and LAPACK (Linear Algebra PACKage) Library APIs is in order.

Re: How to Design an Application Programmers' Interface (API)

[Keith Thompson]

"E. Robert Tisdale" <edwin@netwood.net> writes:
> Be patient Keith,
> 
> You may find what I have to say
> about the GSL (GNU Scientific Library) API very interesting.
> But first,
> I think a critique of the BLAS (Basic Linear Algebra Subroutine)
> and LAPACK (Linear Algebra PACKage) Library APIs is in order.

But not in all these newsgroups.  Please.

-- 
Keith Thompson (The_Other_Keith) kst@cts.com  <http://www.ghoti.net/~kst>
San Diego Supercomputer Center           <*>  <http://www.sdsc.edu/~kst>
Welcome to the last year of the 20th century.

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Keith Thompson wrote:

> But not in all these newsgroups.  Please.

The GSL API has an ANSI C language binding.
The BLAS library and the LAPACK APIs
have Fortran 77, Fortran 90, ANSI C and C++ language bindings.
Which language newsgroups should I leave out?

Re: How to Design an Application Programmers' Interface (API)

[Keith Thompson]

"E. Robert Tisdale" <edwin@netwood.net> writes:
> Keith Thompson wrote:
> 
> > But not in all these newsgroups.  Please.
> 
> The GSL API has an ANSI C language binding.
> The BLAS library and the LAPACK APIs
> have Fortran 77, Fortran 90, ANSI C and C++ language bindings.
> Which language newsgroups should I leave out?

comp.lang.ada for starters.  Probably all of them, unless you're
talking about language issues.

-- 
Keith Thompson (The_Other_Keith) kst@cts.com  <http://www.ghoti.net/~kst>
San Diego Supercomputer Center           <*>  <http://www.sdsc.edu/~kst>
Welcome to the last year of the 20th century.

How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

The class library developer writes library functions, perhaps professionally,
which other programmers will use to write application programs.
The application programmer is the person who actually writes programs,
perhaps professionally, and is not just another library developer.
The library developers and application programmers negotiate
an Application Programmers' Interface (or an Application Program Interface)
so that they can work more or less independently of each other.
Usually, this negotiation amounts to nothing more than
application programmers accepting one of the existing class libraries
which may or may not be implementations of an existing standard API.
(A standard API permits programmers to write portable applications
 even if the libraries themselves are not portable.)
The assumption is that there are just a few library developers
and many application programmers so that the cost of developing
and maintaining a library can be amortized over several applications.

An API specifies the Abstract Data Type (ATD)
which the library supports together with a language binding
for each of the supported computer programming languages.
The various language bindings may not necessarily resolve
to exactly the same objects in a library archive
because that is an implementation issue
which is best left up to the library developer.
Usually, the API does not specify interoperability
between programs and subroutines written in different languages.

The secret to designing a good API is abstraction.
The API should specify no more detail about the actual data representation
or algorithm implementation than is necessary to provide a practical API.
There is virtually no penalty for abstraction built into modern,
object oriented computer programming languages like C++.
Unfortunately, some C++ compilers still impose a penalty for abstraction
but there is usually a suitable workaround that is transparent
to the application programmer so the problem is manageable.
Older computer programming languages, such as Fortran 77, won't even permit
library developers to substitute synonyms for built-in types
let alone permit library developers to define new types
so abstraction can be very difficult to preserve.

A good API, like anything else, should be designed from the top down.
Now, of course, everyone should be aware that good engineering requires
several cycles of top down and bottom up design.
All top down design really means is that the first stroke is top down.
The design should begin with the abstractions
which are to be resolved in the implementation.
The first implementation should expose most of the practical difficulties
of the design which can be used to work back up
to eventually resolve problems with the original abstraction.
Some care should be taken to consider all possible
alternate data representations and algorithm implementations so that
the API does preclude any reasonable representation or implementation.

It is important to be very precise about the definition of the ADT.
Once the ADT is correctly and precisely identified,
designing the rest of the API is relatively straight forward.
A vague description of an ADT which is too general to implement efficiently
is probably better represented by two or more similar but distinct ADTs
each of which can be implemented efficiently.

The API should specify all of the functionality required to support the ADT.
This is almost as easy to do as it is to say for the classical ADTs
which are implemented in the standard C++ library -- list, queue, etc.
But it can be a nontrivial task for the ADTs
supported by a numerical class library for example.
There appear to be a very large number of functions
that operate on vector, matrix and tensor objects.
The API should specify all of this functionality
even if it doesn't require that library developers support all of it.
The reason is that application programmers are going to implement
unsupported functionality whether it is specified or not.
But, if it is specified, application programmers can, at least,
implement the functionality as specified by the API
so that other application programmers will be able
to more easily read, understand and maintain the application source code.
In other words, the API need not mandate everything that it specifies.
The API should mandate only that functionality
which is required to implement the all of the specified functionality
so that application programmers can write portable versions
of the specified functions to replace any missing functionality.
This liberates library developers to implement as much or as little
of the remaining functionality as they see fit.

Application programmers who write their own libraries
are at a natural disadvantage when it comes to designing an API
because they virtually always have a particular implementation in mind
and begin to code before they define the ADT precisely.
They only discover their mistake when they realize that
they need to change the data representation or algorithm implementation
and find themselves searching through their application source code
to find all of the references that need to be changed.

The API designer preserves abstraction by hiding the actual details
of the data representation and algorithm implementation
from application programs so that application programmers
don't accidently reference them directly.
These details are not necessarily secret.
They may be published in documents or even source code
but they should be distinguished (and separated if possible)
from the specification of the API.
C++ API implementations hide the details of the actual
data representation behind a simple private: or protected: label
and provide member functions to access them.
C API implementations use opaque data types to hide private data members.
C++ API implementations use inline functions to avoid the abstraction penalty.
C API implementations may be obliged to use preprocessor macros
to avoid the abstraction penalty.
Fortran 77 requires custom preprocessing to avoid the abstraction penalty.

API designers seldom take abstraction seriously enough.
Generally, it's a good idea to take advantage of existing
especially standard data types but it is seldom a good idea
to expose such implementation details to the application program.
Usually, simple synonyms are sufficient to provide the required abstraction.
For example,

        typedef float   Single;
        typedef double  Double;
        typedef int     Integer;
        typedef size_t  Size;

may permit programmers to write more portable application source code
if they use the synonyms instead of the built-in types.

Re: How to Design an Application Programmers' Interface (API)

[Jack Klein]

On Thu, 10 Aug 2000 02:20:40 +0000, "E. Robert Tisdale"
<edwin@netwood.net> wrote in comp.lang.c:

> The class library developer writes library functions, perhaps professionally,

	[snip]

> object oriented computer programming languages like C++.
> Unfortunately, some C++ compilers still impose a penalty for abstraction

	[snip]

> which are implemented in the standard C++ library -- list, queue, etc.

	[snip]

> C++ API implementations hide the details of the actual

	[snip]

> C++ API implementations use inline functions to avoid the abstraction penalty.

	[snip]

I give up.  You very occasionally post an actual coherent, correct
reply to a question, then you generate utter stupidity like this.

>         typedef float   Single;
>         typedef double  Double;
>         typedef int     Integer;
>         typedef size_t  Size;

The four lines above are just moronic.

You crossposted this to a C, C++, FORTRAN, and Ada newsgroup.  C++,
FORTRAN, and Ada are off-topic in comp.lang.c.  FORTRAN and Ada are
off-topic in comp.lang.c++.  There isn't a single mention of Ada in
your entire post.

The typedef keyword exists in FORTRAN and Ada?

*Plonk* and good riddance, moron.

Jack Klein
-- 
Home: http://jackklein.home.att.net

Re: How to Design an Application Programmers' Interface (API)

[Kaz Kylheku]

On Thu, 10 Aug 2000 02:20:40 +0000, E. Robert Tisdale <edwin@netwood.net> wrote:
>The class library developer writes library functions, perhaps professionally,
>which other programmers will use to write application programs.

Not a bad article overall, especially for a net.kook, but in the future please
refrain from initiating cross-posted discussion threads.

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Kaz Kylheku wrote:

Not a bad article overall, especially for a net.kook,
but in the future please refrain
from initiating cross-posted discussion threads.

Don't be silly.
API design is relevant to all languages.

Re: How to Design an Application Programmers' Interface (API)

[vrml3d.com]

E. Robert Tisdale <edwin@netwood.net> wrote in message
news:39922F55.94087B9E@netwood.net...
> Kaz Kylheku wrote:

>
> Don't be silly.
> API design is relevant to all languages.

Why all the fuss about API design?  3.14159 is usually good enough, and if
you need more precision there are plenty of places to get it.  :)

--Steve

Re: How to Design an Application Programmers' Interface (API)

[Tony T. Warnock]

"vrml3d.com" wrote:

> E. Robert Tisdale <edwin@netwood.net> wrote in message
> news:39922F55.94087B9E@netwood.net...
> > Kaz Kylheku wrote:
>
> >
> > Don't be silly.
> > API design is relevant to all languages.
>
> Why all the fuss about API design?  3.14159 is usually good enough, and if
> you need more precision there are plenty of places to get it.  :)
>
> --Steve

For the same number of characters one can even use 355/113.

Re: How to Design an Application Programmers' Interface (API)

[Toon Moene]

Tony T. Warnock wrote:
> 
> "vrml3d.com" wrote:
> 
> > E. Robert Tisdale <edwin@netwood.net> wrote in message
> > news:39922F55.94087B9E@netwood.net...
> > > Kaz Kylheku wrote:
> >
> > >
> > > Don't be silly.
> > > API design is relevant to all languages.
> >
> > Why all the fuss about API design?  3.14159 is usually good enough, and if
> > you need more precision there are plenty of places to get it.  :)
> >
> > --Steve
> 
> For the same number of characters one can even use 355/113.

Depends on whether the trailing period is part of 113 or just concluding
the sentence.

-- 
Toon Moene - mailto:toon@moene.indiv.nluug.nl - phoneto: +31 346 214290
Saturnushof 14, 3738 XG  Maartensdijk, The Netherlands
GNU Fortran 77: http://gcc.gnu.org/onlinedocs/g77_news.html
GNU Fortran 95: http://g95.sourceforge.net/ (under construction)

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

A good API makes it easier for application programmers to write
safe and reliable high performance application programs clearly
and concisely so that they are easier to read, understand and maintain.
It permits library developers and application programmers
to work independently of each other and reduces the time required
to develop, debug and test applications.

An API is a contract between library developers and application programmers.
It liberates library developers to implement the API as they see fit
by concealing the actual data representation and algorithm implementation
but it must also provide application programmers with all the functionality
required to manipulate the ADT so that they are not obliged
to reach around the API and access the actual data representation directly.
The trick is to do all this without imposing any abstraction penalty
especially if the abstraction doesn't yield any tangible benefit.

I know numerical library API designs best so I will use them as examples.
There are lots of really good numerical library API designs
but they aren't always as instructive as really poor API designs.

The BLAS library API

        http://www.netlib.org/blas/

was designed to help numerical library developers implement
high performance linear algebra packages
and wasn't really meant to be used by application programmers.*
It supports strided real and complex multidimensional views
of one dimensional arrays of real numbers
which are useful in many more applications
than linear algebra but no other functionality is specified.
Part of the problem with the BLAS library API can be traced
back to the original Fortran 77 implementation.
Fortran 77 isn't very friendly to API designers.
It doesn't provide any mechanisms to define new data types
or even to define synonyms for existing data types
and it doesn't provide any effective mechanism to hide
the actual data representation.  Abstraction is supported only through
the self discipline of cooperative application programmers.
The only practical place to construct vector and matrix view objects
in a Fortran 77 program is in the argument list of subroutine calls.
The result is long argument lists as in

      SUBROUTINE DGEMM(
     $  TRANSA, TRANSB, M, N, K, ALPHA, A, LDA, B, LDB, BETA, C, LDC)
*     .. Scalar Arguments ..
      CHARACTER*1        TRANSA, TRANSB
      INTEGER            M, N, K, LDA, LDB, LDC
      DOUBLE PRECISION   ALPHA, BETA
*     .. Array Arguments ..
      DOUBLE PRECISION   A(LDA, *), B(LDB, *), C(LDC, *)

which computes C <-- alpha*AB + beta*C
from an m by k matrix A, a k by n matrix B and an m by n matrix C.
These long argument lists are as hard to write as they are to read
and they are expensive to pass to the BLAS library.

BLAS matrix view objects are restricted to unit stride within any column
and positive stride (leading dimension) within any row
greater than the extent of any column.
Fortran 77 is, again, mostly responsible for the restriction to unit stride.
Numerical algorithms that operate on matrix views generally work best
with unit stride between the elements of a column (or row)
but it isn't practical for the BLAS library to examine the strides
and condense matrix views with arbitrary stride
into a temporary matrix with unit stride because there is no way
to allocate the required array storage dynamically in Fortran 77.

There are about 150 subroutines altogether in the BLAS library
for both single and double precision real and complex numbers.
There should have been many more subroutines
but BLAS library developers complained so some functionality was dropped
but some functionality was preserved by passing extra options
to the remaining subroutines.  This means that instead of resolving
functionality in the subroutine name space at compile time, it must
be resolved at run time by testing options passed in the argument list.
This extra overhead is negligible
for operations on large vector and matrix objects
but virtually precludes their use on small objects in tight loops.
These compromises in the design and specification of the BLAS library API
result in too many arbitrary rules and exceptions
that are difficult for application programmers to learn and remember
and provide too many opportunities to make programming errors
which are difficult to detect and debug.

Unfortunately, the C, C++ and Fortran 90 language bindings
don't improve the BLAS library API very much.
They are basically very thin interfaces for the Fortran 77 implementation
and don't really support any of the functionality
missing from the original Fortran 77 implementation.

So what went wrong with the BLAS library API design process?
Well, first of all, the BLAS library API designers probably never did
precisely identify the ADT that they wanted to support.
Second, they never realized the advantage of specifying functionality
that they couldn't compel BLAS library developers to support.
Third, they couldn't anticipate the advantages of specifying abstraction
that Fortran 77 couldn't support.
Fourth, by the time the got around to specifying other language bindings,
they had already forgotten about basic design principles.


* The C++ Matrix Template Library (MTL)

        http://www.lsc.nd.edu/research/mtl/

  was also designed to help library developers
  implement high performance numerical algorithms in C++
  and really isn't useful to application programmers.

Re: How to Design an Application Programmers' Interface (API)

[David Gillon]

"E. Robert Tisdale" wrote:
> 
> Keith Thompson wrote:
> 
> > But not in all these newsgroups.  Please.
> 
> The GSL API has an ANSI C language binding.
> The BLAS library and the LAPACK APIs
> have Fortran 77, Fortran 90, ANSI C and C++ language bindings.
> Which language newsgroups should I leave out?

I'd suggest comp.software-eng as the appropriate forum for this
discussion rather than a language specific group.

-- 

David Gillon

Re: How to Design an Application Programmers' Interface (API)

[Larry Kilgallen]

In article <399386EF.4F2AA3E6@netwood.net>, "E. Robert Tisdale" <edwin@netwood.net> writes:
> A good API makes it easier for application programmers to write
> safe and reliable high performance application programs clearly
> and concisely so that they are easier to read, understand and maintain.
> It permits library developers and application programmers
> to work independently of each other and reduces the time required
> to develop, debug and test applications.

But library developers and application programmers can work
independently even with a lousy API design, so long as they
use the Ada language.  Write the specification for the library
first (it can even be written by the application programmer)
and then have each side code using that specification.

> An API is a contract between library developers and application programmers.

And the implementation of that contract is the specification of
the library package.

If you are going to post these generalities to the Ada newsgroup,
please be aware of the features of the Ada language.

Re: How to Design an Application Programmers' Interface (API)

[David Botton]

Although, Ada does have bindings to LAPACK, etc.

David Botton

"Keith Thompson" <kst@cts.com> wrote in message
news:yecu2cs200i.fsf@king.cts.com...
> > The GSL API has an ANSI C language binding.
> > The BLAS library and the LAPACK APIs
> > have Fortran 77, Fortran 90, ANSI C and C++ language bindings.
> > Which language newsgroups should I leave out?
>
> comp.lang.ada for starters.  Probably all of them, unless you're
> talking about language issues.

Re: How to Design an Application Programmers' Interface (API)

[Gautier]

E. Robert Tisdale:

> Unfortunately, the C, C++ and Fortran 90 language bindings
> don't improve the BLAS library API very much.

You may take a look to the Ada95 binding to BLAS :

  http://topo.math.u-psud.fr/~sands/BLAS/

______________________________________________________
Gautier  --  http://members.xoom.com/gdemont/gsoft.htm

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Larry Kilgallen wrote:

> But library developers and application programmers
> can work independently even with a lousy API design,
> so long as they use the Ada language.
> Write the specification for the library first
> (it can even be written by the application programmer)
> and then have each side code using that specification.

Please explain what you mean by API.
I believe that your specification is a specification of the API
or, at least, the specification of the Ada language binding.

> > An API is a contract
> > between library developers and application programmers.
>
> And the implementation of that contract
> is the specification of the library package.
>
> If you are going to post these generalities to the Ada newsgroup,
> please be aware of the features of the Ada language.

Why?
Because Ada deals with them formally and explicitly?
I'm not advocating any one computer programming language
over another.  But please feel free to do so if you wish.

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Gautier wrote:

> E. Robert Tisdale:
>
> > Unfortunately, the C, C++ and Fortran 90 language bindings
> > don't improve the BLAS library API very much.
>
> You may take a look to the Ada95 binding to BLAS :
>
>   http://topo.math.u-psud.fr/~sands/BLAS/

These thin interfaces to another language binding are called adapters.
You have implemented a very nice adapter but I'm not sure why.
Your adapter isn't really any more useful to Ada application programmers
than the Fortran 77 language binding is to Fortran application programmers.
Is it meant to help programmers implement linear algebra packages in Ada
for Ada numerical application programmers to use?

I think that Ada numerical application programmers should be able to write

    C := alpha*product(A, B) + beta*C;

and let the compiler resolve the expression to a DGEMM procedure call.
Calling DGEMM directly from an Ada application program
abrogates all of the safety feature built into the Ada language.

Take a look at the Ada95 Matrix Package

    http://dflwww.ece.drexel.edu/research/ada/

Chris Papademetrious, Xiaoxun Zhu, Moshe Kam had the right idea
but the wrong Abstract Data Type.
An Ada95 Matrix Package should support strided views (slices)
of existing arrays of numbers like every other high performance
matrix library developed over the last 50 years.
The actual details of allocating and deallocating memory
for array storage may vary slightly from one language binding to the next.

Re: How to Design an Application Programmers' Interface (API)

[Gautier]

> Gautier wrote:
> > You may take a look to the Ada95 binding to BLAS :
> >   http://topo.math.u-psud.fr/~sands/BLAS/

E. Robert Tisdale:

> These thin interfaces to another language binding are called adapters.
> You have implemented a very nice adapter but I'm not sure why.

I fear you haven't noticed that it is not my work at all...

> Your adapter isn't really any more useful to Ada application programmers
> than the Fortran 77 language binding is to Fortran application programmers.
> Is it meant to help programmers implement linear algebra packages in Ada
> for Ada numerical application programmers to use?

It seems.

> I think that Ada numerical application programmers should be able to write

>     C := alpha*product(A, B) + beta*C;

> and let the compiler resolve the expression to a DGEMM procedure call.

For scalar things or usage with small vectors or matrices as output of
functions I would do so. For bigger structures the procedure is better
- no temporary object in expressions. In my own (partial) bindings I have
both approaches.

> Calling DGEMM directly from an Ada application program
> abrogates all of the safety feature built into the Ada language.

It depends on the ratio of BLAS/LAPACK calls in the Ada code. For my
finite element program the "adapter" fits: there are a few calls that
separates well the 1960s programming models to my year 2000 sources...
It firewalls efficiently the weak-typing headaches and I can add
degrees of complexity with joy and decontraction...
 
Anyway you can wrap the adapter into some "Multiply" etc. procedures -
as well as "*" etc. functions.

> Take a look at the Ada95 Matrix Package
>
>     http://dflwww.ece.drexel.edu/research/ada/
> 
> Chris Papademetrious, Xiaoxun Zhu, Moshe Kam had the right idea
> but the wrong Abstract Data Type.
> An Ada95 Matrix Package should support strided views (slices)
> of existing arrays of numbers like every other high performance
> matrix library developed over the last 50 years.
> The actual details of allocating and deallocating memory
> for array storage may vary slightly from one language binding to the next.

Seems very elegant, but it might be not very efficient
- functional-only, and things like "RESULT := (others => (others => 0.0));"
I don't know of a compiler that just zeroes rapidly RESULT (also
a temp. variable BTW)...

Regards
______________________________________________________
Gautier  --  http://members.xoom.com/gdemont/gsoft.htm

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Gautier wrote:

> > I think that Ada numerical application programmers should be able to write
>
> >     C := alpha*product(A, B) + beta*C;
>
> > and let the compiler resolve the expression to a DGEMM procedure call.
>
> For scalar things or usage with small vectors
> or matrices as output of functions, I would do so.
> For bigger structures the procedure is better
> - no temporary object in expressions.
> In my own (partial) bindings I have both approaches.

Why do you assume that the above expression involves temporaries?
C++ programmers can implement libraries which resolve this expression
to a DGEMM subroutine call.  Why can't Ada 95 programmers do the same?

> > Calling DGEMM directly from an Ada application program
> > abrogates all of the safety feature built into the Ada language.
>
> It depends on the ratio of BLAS/LAPACK calls in the Ada code.
> For my finite element program the "adapter" fits:
> there are a few calls that well separate the 1960s programming models
> from my year 2000 sources...
> It firewalls efficiently the weak-typing headaches
> and I can add degrees of complexity with joy and decontraction...
>
> Anyway you can wrap the adapter into some "Multiply" etc. procedures -
> as well as "*" etc. functions.

But now you have two interfaces.
Wouldn't it have been better to redesign the API
and implement it with calls to the BLAS Fortran language binding?

> Seems very elegant, but it might be not very efficient
> - functional-only, and things like "RESULT := (others => (others => 0.0));"
> I don't know of a compiler that just zeroes rapidly RESULT
> (also a temp. variable BTW)...

We can nitpick forever about the implementation of the API.
The question is whether the API will permit us to substitute
a better implementation or not.  A good API will.  A bad API won't.

Re: How to Design an Application Programmers' Interface (API)

[Larry Kilgallen]

In article <39940266.15161093@netwood.net>, "E. Robert Tisdale" <edwin@netwood.net> writes:
> Larry Kilgallen wrote:
> 
>> But library developers and application programmers
>> can work independently even with a lousy API design,
>> so long as they use the Ada language.
>> Write the specification for the library first
>> (it can even be written by the application programmer)
>> and then have each side code using that specification.
> 
> Please explain what you mean by API.
> I believe that your specification is a specification of the API
> or, at least, the specification of the Ada language binding.
> 
>> > An API is a contract
>> > between library developers and application programmers.
>>
>> And the implementation of that contract
>> is the specification of the library package.
>>
>> If you are going to post these generalities to the Ada newsgroup,
>> please be aware of the features of the Ada language.
> 
> Why?
> Because Ada deals with them formally and explicitly?
> I'm not advocating any one computer programming language
> over another.  But please feel free to do so if you wish.

If you want to discuss specifics, please trim the discussion to
comp.lang.ada only.  If you want to discuss generalities, please
remove comp.lang.ada.  Your generalities are totally out of place
in comp.lang.ada and only lead to noisy fruitless extended wasted
threads if past experience is any guide.

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Larry Kilgallen wrote:

> If you want to discuss specifics,
> please trim the discussion to comp.lang.ada only.
> If you want to discuss generalities,
> please remove comp.lang.ada.
> Your generalities are totally out of place in comp.lang.ada
> and only lead to noisy fruitless extended wasted threads
> if past experience is any guide.

Thank you for your opinion,
Please just ignore this thread
if you aren't interested in contributing to it.
Or, trim the discussion to comp.lang.ada
if you are only interested is discussing issues particular to Ada.

Interfacing to Numerical Programming libraries (was: How to Design..)

[Larry Kilgallen]

In article <3994158E.150D1FDA@netwood.net>, "E. Robert Tisdale" <edwin@netwood.net> writes:

> These thin interfaces to another language binding are called adapters.

Here in comp.lang.ada they are called thin bindings.

> You have implemented a very nice adapter but I'm not sure why.

As indicated in _many_ previous threads, some people like thin bindings
and some people like thick bindings.  Some projects are best done with
thin bindings and some projects are best done with thick bindings.

> I think that Ada numerical application programmers should be able to write
> 
>     C := alpha*product(A, B) + beta*C;
> 
> and let the compiler resolve the expression to a DGEMM procedure call.

More precisely, the thick binding (including even some code)
would take care of calling your library.  Certainly that is
a fine strategy to follow, just not the one cited.

Re: How to Design an Application Programmers' Interface (API)

[Peter S. Shenkin]

By the way, I have an article on this subject in the March, 2000, ACM
Fortran Forum.

--
Peter S. Shenkin
Work:  shenkin@schrodinger.com;  Play: shenkin@mindspring.com

Re: Interfacing to Numerical Programming libraries (was: How to Design..)

[E. Robert Tisdale]

Larry Kilgallen wrote:

> In article <3994158E.150D1FDA@netwood.net>,
> "E. Robert Tisdale" <edwin@netwood.net> writes:
>
> > These thin interfaces to another language binding are called adapters.
>
> Here in comp.lang.ada they are called thin bindings.

Bindings to what?
The BLAS library API does not specify any language for implementation.
It might be implemented in Ada 95, in which case,
your "thin binding" would be unnecessary overhead.

> > You have implemented a very nice adapter but I'm not sure why.
>
> As indicated in _many_ previous threads,
> some people like thin bindings and some people like thick bindings.
> Some projects are best done with thin bindings and
> some projects are best done with thick bindings.

That's not the issue here.
Ada 95 library developers are not obliged to reproduce the "compromises"
incorporated into the design of the Fortran 77 language binding.
Ada 95 provides them with all of the language features required
to design a really good language binding for the BLAS library
and they should take advantage of them.

> > I think that Ada numerical application programmers should be able to write
> >
> >     C := alpha*product(A, B) + beta*C;
> >
> > and let the compiler resolve the expression to a DGEMM procedure call.
>
> More precisely, the thick binding (including even some code)
> would take care of calling your library.
> Certainly that is a fine strategy to follow, just not the one cited.

DGEMM is an Ada 95 procedure here -- not a Fortran 77 subroutine.
Your notion of a "thick binding" doesn't appear to apply.
But I agree.
There is no reason why an Ada 95 package shouldn't be able to {\em fuse }
the five operations in the above expression into a single procedure call.

Re: Interfacing to Numerical Programming libraries (was: How to Design..)

[tmoran]

>Ada 95 library developers are not obliged to reproduce the "compromises"
>incorporated into the design of the Fortran 77 language binding.
  Unless they want the bindings to be easily used by folks familiar
with the F77 binding, or they want to avoid spending a lot of time
developing and documenting their "thick" binding, and instead want
to just point application programmers to the existing F77 manuals.
  If the underlying library is a rapidly changing thing (eg, Windows),
they might well decide it's not worth the trouble to try to modify
their "thick" API and its documentation every time MS adds a new
set of functions.  Perhaps it's only worth running a program to
mechanically translate the new API calls from one language to another.
---
Now to leave town for a few days....

Re: Interfacing to Numerical Programming libraries (was: How to Design..)

[E. Robert Tisdale]

tmoran@bix.com wrote:

> > Ada 95 library developers are not obliged to reproduce the "compromises"
> > incorporated into the design of the Fortran 77 language binding.
>
> Unless they want the bindings to be easily used
> by folks familiar with the F77 binding,
> or they want to avoid spending a lot of time
> developing and documenting their "thick" binding
> and,  instead, want to just point application programmers
> to the existing F77 manuals.
> If the underlying library is a rapidly changing thing (eg, Windows),
> they might well decide it's not worth the trouble
> to try to modify their "thick" API and its documentation
> every time MS adds a new set of functions.
> Perhaps it's only worth running a program
> to mechanically translate the new API calls
> from one language to another.
> ---
> Now to leave town for a few days....

I think you'd better.  Listening to you,
it sound like no one ever implements libraries in Ada 95 --
they just write thick and thin "bindings" to access libraries
written in other programming languages;-)

You can design and implement an Ada 95 language binding
that is just as bad as any other language binding.
I'm just assuming that, because Ada 95 allows programmers
to design and implement a good language binding,
some of them might wish to do so.

Re: Interfacing to Numerical Programming libraries (was: How to Design..)

[Sam Hobbs]

On 11 Aug 2000 22:16:45 -0500, Kilgallen@eisner.decus.org.nospam
(Larry Kilgallen) wrote:

>In article <3994158E.150D1FDA@netwood.net>, "E. Robert Tisdale" <edwin@netwood.net> writes:
>
>> These thin interfaces to another language binding are called adapters.
>  <<snip>>
>
>> I think that Ada numerical application programmers should be able to write
>> 
>>     C := alpha*product(A, B) + beta*C;
>> 

Any relevance to C ??

Sam

Re: How to Design an Application Programmers' Interface (API)

[Gregory Pietsch]

"E. Robert Tisdale" wrote:
> 
> The ANSI C computer programming language
> does not support Object Oriented Programming very well.

Of course not.  It was never an OOP language.

> It has an encapsulation mechanism (struct) for creating new types
> and a mechanism (typedef) for creating synonyms for existing types
> but it doesn't really provide any mechanism
> for hiding the data members of a struct except for opaque data types.

Yawn... That's because we C programmers don't even WANT any mechanism
for hiding the data members.

> The definition of an opaque data type
> is never exposed to the application program
> so the only way to create, manipulate and destroy opaque data types
> is by passing pointers to library functions.
> This means that memory for all opaque data types
> must be allocated from free storage (on the heap)
> which can involve significant overhead for small objects.

e.g. FILE in <stdio.h>.

> Another, less effective, method
> for hiding the private data members of a struct in ANSI C
> is to provide the application program with a dummy type definition
> 
>         typedef struct {
>           int dummy[new_type_size/sizeof(int)];
>           } new_type;
> 
> which is the same size as the new type
> but conceals the name and location of all private data members.
> The advantage of dummy type definitions is that memory for them
> may be allocated from automatic storage (on the stack)
> with virtually no overhead.

In other words, a union of the real type with an array of int (or char)
the same size?  What fun.

> 
> The problem with opaque data types and dummy type definitions is that
> none of the functions that create, manipulate and destroy them
> can be implemented as inline functions or C preprocessor macros.
> This problem is solved by using library functions
> together with opaque data types or dummy type definitions
> during program development, debugging and testing
> then, just before placing the application into service,
> the private type definition is substituted
> for the opaque or dummy data type definition,
> the inline functions and/or C processor macros are substituted
> for the external library functions
> and the application program is recompiled.

Seems a little complicated.  Why don't I just write the program?

> The advantage of using the external library functions
> during application program development, debugging and testing
> is that application programs usually compile faster
> if they don't need to process inline functions or C preprocessor macros
> and the compiler can diagnose programming errors more precisely.

> Application programmers must NOT be obliged
> to access private data members directly.

Fine.  Whenever I write C++ programs, I'll avoid adding get/set methods.

> The library must provide functions
> which application programmers can use
> to create, manipulate and destroy objects as efficiently as possible.

Don't have a problem with that.
 
> If the library API fails to specify such functions
> and programmers write applications
> which access private data members directly,
> library developers will never be able to change
> the actual data representation,
> the meaning of any data member
> or even the name of any data member
> without breaking existing application programs.
> But, if the library API specifies such functions
> and library developers make a reasonable attempt
> to hide the actual type definition and private data members
> so that applications programmers can't access them directly by accident,
> then library developers are at liberty to change the data representation,
> including the meaning, location, name and number of data members
> at any time just by redefining the library functions
> that access them directly and redistributing the library.

This is getting into OO philosophy more than anything.

Later, Gregory Pietsch

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Gregory Pietsch wrote:

> Of course not.  It was never an OOP language.
>
> That's because we C programmers don't even WANT
> any mechanism for hiding the data members.

They certainly do.

> In other words,
> a union of the real type with an array of int (or char) the same size?

No.
There are two definitions -- one private and one public.
Only library functions have access to the private type definition.
Application programs can only include the public type definition.

> Seems a little complicated.  Why don't I just write the program?

It isn't complicated.
You just write the program which 'include's the library header file.
When you've finished debugging and testing your program,
you simply define a C preprocessor macro
which selects the static inline functions
instead of the external library function prototypes and you recompile.

> Fine.  Whenever I write C++ programs, I'll avoid adding get/set methods.
>
> This is getting into OO philosophy more than anything.

No.  It's not just philosophy.
It's just good design practice.  Until you understand that,
you won't be a competent programmer in ANY language.

Re: How to Design an Application Programmers' Interface (API)

[Gregory Pietsch]

"E. Robert Tisdale" wrote:
> 
> Gregory Pietsch wrote:
> 
> > Of course not.  It was never an OOP language.
> >
> > That's because we C programmers don't even WANT
> > any mechanism for hiding the data members.
> 
> They certainly do.

If they wanted it, they'd be C++ programmers.  C is not C++.  Why not
cut through all the layers of OO obfuscation right down to the bare
metal?  That's what C gives you and C++ does not.

> 
> > In other words,
> > a union of the real type with an array of int (or char) the same size?
> 
> No.
> There are two definitions -- one private and one public.
> Only library functions have access to the private type definition.
> Application programs can only include the public type definition.

Ah, yes -- the distinction between the interface and the
implementation.  This is fundamental to OO.

> 
> > Seems a little complicated.  Why don't I just write the program?
> 
> It isn't complicated.
> You just write the program which 'include's the library header file.
> When you've finished debugging and testing your program,
> you simply define a C preprocessor macro
> which selects the static inline functions
> instead of the external library function prototypes and you recompile.

If I did that, I'd have to retest it to make sure that it worked.  You
can't be too careful.

> > Fine.  Whenever I write C++ programs, I'll avoid adding get/set methods.
> >
> > This is getting into OO philosophy more than anything.
> 
> No.  It's not just philosophy.
> It's just good design practice.  Until you understand that,
> you won't be a competent programmer in ANY language.

The one thing that made me sick about C++ when I first encountered it
was that philosophical aspect.  If you weren't doing things the way that
the high priests wanted you to, you'd be banished to writing payroll
programs in RPG, or worse, being called an unwashed heathen who was
unworthy even to enter the computer room.  OO has been hyped so much
that you'd figure that it would solve world hunger and usher in an era
of world peace.  NOT!  OO is a tool; that's all it is.  I AM a competent
C programmer; one visit to Richard Heathfield's K&R2 site would prove it
(I've written about a dozen answers to the K&R2 problems).

Later, Gregory Pietsch

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

Brendan Sechter <sgeos@granicus.if.org> wrote:

> Why hide anything?

So that the application programmer doesn't access
private data members directly by accident.

> Do not you have the option not to use it?

You use it only through library function calls
so that your application program will work
even if the definition of the data type changes
when you install a newer version of the library.


Gregory Pietsch wrote:

> If they wanted it, they'd be C++ programmers.  C is not C++.
> Why not cut through all the layers of OO obfuscation
> right down to the bare metal?
> That's what C gives you and C++ does not.
>
> Ah, yes --
> the distinction between the interface and the implementation.
> This is fundamental to OO.

No.  It doesn't necessarily have anything to do with objects.
It's just good programming practice and always has been.

> If I did that, I'd have to retest it to make sure that it worked.
> You can't be too careful.

Good for you!  But we're assuming here that
the library has already been thoroughly tested
so retesting shouldn't be necessary.

> The one thing that made me sick about C++
> when I first encountered it was that philosophical aspect.
> If you weren't doing things the way that the high priests wanted you to,
> you'd be banished to writing payroll programs in RPG,
> or worse, being called an unwashed heathen
> who was unworthy even to enter the computer room.
> OO has been hyped so much that you'd figure that
> it would solve world hunger and usher in an era of world peace.  NOT!
> OO is a tool; that's all it is.  I AM a competent C programmer;
> one visit to Richard Heathfield's K&R2 site would prove it
> (I've written about a dozen answers to the K&R2 problems).

This is all gobbledegook to you isn't it?  No,
OOP isn't going to solve world hunger and usher in an era of world peace.
It just makes it a lot easier to write safe and reliable computer programs
that other programmers can read, understand and maintain.
Good programmers can wade through all of the hype about OOP
and learn to use it effectively.  Hackers can't.
You may be able to program in C to your own satisfaction
but until you can understand the code that other C programmers are writing
and learn to write code the way that they do, you will remain a hacker
and no one will trust you with important programming assignments.

Re: How to Design an Application Programmers' Interface (API)

[Larry Kilgallen]

In article <3996456C.CAD018D5@netwood.net>, "E. Robert Tisdale" <edwin@netwood.net> writes:
> The ANSI C computer programming language
> does not support Object Oriented Programming very well.

So why do you persist in posting this in comp.lang.ada ?

Re: How to Design an Application Programmers' Interface (API)

[Larry Kilgallen]

"E. Robert Tisdale" <edwin@netwood.net> writes:

> Larry Kilgallen wrote:
> 
> > In article <3996456C.CAD018D5@netwood.net>,
> > "E. Robert Tisdale" <edwin@netwood.net> writes:
> > > The ANSI C computer programming language
> > > does not support Object Oriented Programming very well.
> >
> > So why do you persist in posting this in comp.lang.ada?
> 
> Because the same remark applies to Ada 83?

Participants in comp.lang.ada are well aware of the difference
between Ada83 and Ada95.  In fact, it forms a basis for their
choice of compilers.

> Obviously, you just don't get it yet.
> Be patient and keep reading or just ignore this thread.

Please restrict the thread to those newsgroup where it applies.

Re: How to Design an Application Programmers' Interface (API)

[E. Robert Tisdale]

The ANSI C computer programming language
does not support Object Oriented Programming very well.
It has an encapsulation mechanism (struct) for creating new types
and a mechanism (typedef) for creating synonyms for existing types
but it doesn't really provide any mechanism
for hiding the data members of a struct except for opaque data types.
The definition of an opaque data type
is never exposed to the application program
so the only way to create, manipulate and destroy opaque data types
is by passing pointers to library functions.
This means that memory for all opaque data types
must be allocated from free storage (on the heap)
which can involve significant overhead for small objects.
Another, less effective, method
for hiding the private data members of a struct in ANSI C
is to provide the application program with a dummy type definition

        typedef struct {
          int dummy[new_type_size/sizeof(int)];
          } new_type;

which is the same size as the new type
but conceals the name and location of all private data members.
The advantage of dummy type definitions is that memory for them
may be allocated from automatic storage (on the stack)
with virtually no overhead.

The problem with opaque data types and dummy type definitions is that
none of the functions that create, manipulate and destroy them
can be implemented as inline functions or C preprocessor macros.
This problem is solved by using library functions
together with opaque data types or dummy type definitions
during program development, debugging and testing
then, just before placing the application into service,
the private type definition is substituted
for the opaque or dummy data type definition,
the inline functions and/or C processor macros are substituted
for the external library functions
and the application program is recompiled.
The advantage of using the external library functions
during application program development, debugging and testing
is that application programs usually compile faster
if they don't need to process inline functions or C preprocessor macros
and the compiler can diagnose programming errors more precisely.

Application programmers must NOT be obliged
to access private data members directly.
The library must provide functions
which application programmers can use
to create, manipulate and destroy objects as efficiently as possible.

If the library API fails to specify such functions
and programmers write applications
which access private data members directly,
library developers will never be able to change
the actual data representation,
the meaning of any data member
or even the name of any data member
without breaking existing application programs.
But, if the library API specifies such functions
and library developers make a reasonable attempt
to hide the actual type definition and private data members
so that applications programmers can't access them directly by accident,
then library developers are at liberty to change the data representation,
including the meaning, location, name and number of data members
at any time just by redefining the library functions
that access them directly and redistributing the library.

Re: How to Design an Application Programmers' Interface (API)

[Brendan Sechter]

On Sun, 13 Aug 2000 15:33:34 +0000, E. Robert Tisdale <edwin@netwood.net> wrote:
>Gregory Pietsch wrote:
>
>> Of course not.  It was never an OOP language.
>>
>> That's because we C programmers don't even WANT
>> any mechanism for hiding the data members.
>
>They certainly do.

Why hide anything? Do not you have the option not to use it?

-SG

--
With the amount of idiots in this world....I'll have a fun time filtering
out the defects =P	-Khilent