Parity definitely needs to be maintained between API functions and the
interface in GLOBALS!

The reason I resist splitting the API is that Csound, especially the
multiply instantiable fully re-entrant Csound that we are aiming for, is
after all a single object and thus LOGICALLY _has_ a single interface.
Creating two PHYSICAL interfaces to represent this single logical interface
is of course possible, but it introduces (in my opinion unnecessary)
complexity.

Another reason is that a number of functions are common to both hosts and
plugins (GetSr, ftfind, etc.).

Another factor, not discussed here so far, is that after one creates an
instance of Csound, how does one obtain the host interface or the client
interface? Something like the COM QueryInterface function must be
implemented. (Csound *csound = createCsound(mydata); CsoundHostInterface
*hostInterface = csound->QueryInterface("CsoundHostInterface");
CsoundOpcodeInterface *opcodeInterface =
csound->QueryInterface("CsoundOpcodeInterface")). This also introduces
complexity, but has the advantage that new interfaces can be added at any
time without breaking existing interfaces. Perhaps Richard Dobson was
envisioning something like this. 

I understand your concern, and John's, about presenting to hosts functions
that only should be called by plugins, and vice versa. But it has to be
balanced against the complexity.

Possible solutions:

Go ahead and split the API, duplicating some functions in both halves,
using the QueryInterface technique.

Keep the single interface as a low-level API, and add supplementary
high-level host and plugin APIs.

Rename functions for greater clarity (cshXXX for hosts, csoXXX for opcodes,
csXXX for common functions). This has the advantage that simply renaming
the functions will not break the interface for older plugins as long as the
signatures of the functions do not change.

A compromise incorporating all 3 solutions might be to rename functions in
the existing API, for the sake of greater clarity while preserving backward
compatibility, and add to it the QueryInterface capability for the sake of
separating host and opcode functions. But this could be even more
confusing!...

If I had to choose just one solution, I would prefer to simply rename the
existing functions.


Original Message:
-----------------
From: stevenyi stevenyi@csounds.com
Date: Wed, 19 Nov 2003 09:27:19 -0800
To: csound-dev@eartha.mills.edu
Subject: [CSOUND-DEV:3410] Re: Csound API Split, design


Oh well, I guess it was all just wishful thinking on my part.  Thanks
very much for spending the time to explain all of this; it's probably
been the most I've learned in terms of programming in quite some time. 
(And a as a side effect, I think I'm finally beginning to understand
what my COM programmer friend from my last job was talking about!). 

I think I agree with the author of that email I found that "the MS
engineers were on crack when they designed Windows DLLs".  =)  

But now I'll move on to probably another annoying question: does parity
have to be maintained between the API functions and what function
pointers are in GLOBAL?  I still haven't shaken off that funny feeling
about opcode plugins getting access to csoundCompile, csoundReset, and
other functions that seem very much for host-use only.  

And in regards to pushing everything into csound.h, wouldn't that cause
all the trouble with linking against the host API functions and
requiring libcsound.a?  It seems that the API for hosts and plugins then
*would* have to be split into two files. (I noticed in
csound4/soundfonts the headers only include cs.h and not csound.h).

Thanks again!
steven


On Wed, 2003-11-19 at 06:38, gogins@pipeline.com wrote:
> What you are suggesting works -- but ONLY if Csound ITSELF is a DLL. In
> other words, the scheme you suggest would work for CsoundVST or some other
> DLL version of the Csound API, but it would NOT allow plugin opcodes to
> automagically link with a statically linked Csound APPLICATION.
> 
> I would prefer, indeed, that the base object in the Csound world be a
> Csound API DLL or shared library! And that the command-line version of
> Csound link dynamically to the API library! But as long as that is not
> ALWAYS the case, the function pointer scheme IS the lowest common
> denominator method that WILL work in all cases.
> 
> Furthermore, linking directly with a DLL across versions, as we require,
is
> only possible on Windows through the use of a .def file to define ordinal
> numbers, which introduces another unnecessary complication. So the
function
> table scheme is actually simpler (which is why Microsoft adopted it for
> COM).
> 
> I considered all these issues when I designed the API, and I took into
> consideration advice from other Csound developers. As far as I know, the
> function table scheme is the simplest, most foolproof way to get plugin
> opcodes that can talk back to Csound across version and across platforms.
> 


--------------------------------------------------------------------
mail2web - Check your email from the web at
http://mail2web.com/ .