Interfacing to externals. [offshoot from CompileIt for Revolution]

[Alex Tweedly]

Although there may be changes possible that could reduce the need for 
externals, I believe there will always be good reasons to use externals.

I think the current mechanism used by Rev to do interface to externals 
is missing an opportunity, and indeed is inelegant (or unaesthetic), 
because it forces the interface - and hence the calling Transcript code 
- to be different from what it would be if the function/handler were 
internal (pure Transcript) rather than external. 

[If I've missed something, and there is already such a mechanism, please 
tell me. I know you can retrieve such binary data from within the 
external, but as far as I can tell you cannot *pass* it to an external.]

The mechanism used passes null-terminated strings (an array of them, for 
the parameters) and returns a null-terminated string (if it's a 
function).  This precludes passing, or returning, binary data.

So, in pure Transcript, I would create a function as follows:
function manipulate pImageData
  -- do something to the image data, creating a new image in newImageData
  return newImageData
end manipulate

and call it as
  put the imagedata of img "mine" into myImage
  put manipulate(myImage) into newImage
  set the imagedata of img "destination" to newImage

However, if "manipulate" was to be, or become, an external then you 
cannot provide that interface. You need to change it such the calling 
side looks like
   put the imagedata of img "mine" into myImage
  manipulate "myImage", "newImage"
  set the imagedata of img "destination" to newImage
(or a variant of that. You could keep it as a function - but since its 
result can't be the binary data, there's no reason to do so).

Alternatively, I might be willing to overwrite the original data (and 
save the time for replicating it), and then do
on manipulateInPlace @pImageData
   - change it
end manipulateInPlace

Then it would be called as
  manipulateInPlace myImage

and again if it had to be an external, the interface would need to be
  manipulateInPlace "myImage"

You can't pass binary data because the parameters appear on the C side 
as    char *args[]  
(and similarly the return value is a null-terminated string).

If that could be changed to pass an array of MCStrings (i.e. 
MCstring[])  then, because they'd be length-specified, there would be no 
problem with binary data. Similar change for the return value from a 
function.

Even if this does seem like a desirable change, is it feasible ?

I think it should be. Obviously it wouldn't be possible to "just change" 
because it would be incompatible. But the Xtable[] used to define the 
entry points already contains a "type", currently one of XFUNCTION, 
XCOMMAND or XNONE. The set of types could be extended to include, say, 
XBINFUNCTION and XBINCOMMAND which determine that the paramters and, 
where applicable, return value are MCStrings rather than char *s. 
Therefore the engine would know which parameter passing mechanism is in 
use, and behave accordingly.

The primary benefit is that it alows the interface to be more 
"Transcript-like" - no (regular) pure-Transcript function would expect 
to be passed a string containing the name of a variable in preference to 
passing the variable itself. 

The secondary benefit is that you could initially write a Transcript 
version of the function, and later replace it by an external versino of 
the same function without revisiting every place it is used to change 
the calling convention.

There is a tertiary benefit of minor speed improvement from avoiding the 
callback to retrieve (and set) binary parameters (and results), but I 
don't think that's significant, and it would not be a reason to suggest 
this change.

I don't see any major drawback. There is a minor drawback, in that it is 
an additional mechanism to be learnt  by anyone starting to write 
externals, and to be considered each time you design an external's 
interface. And there is a very minor drawback in that it is extra work 
to develop, and code to maintain, in the engine's external-calling code 
- but I would hope that it shouldn't be much extra code, and shouldn't 
be "fragile", and so not a noticable maintenance cost.


-- 
Alex Tweedly       http://www.tweedly.net



-- 
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.323 / Virus Database: 267.8.0/27 - Release Date: 23/06/2005