eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'ExternalFunction':

Home

Documentation
www.exept.de
Everywhere
for:
[back]

Class: ExternalFunction


Inheritance:

   Object
   |
   +--ExecutableFunction
      |
      +--ExternalFunction
         |
         +--ExternalFunctionCallback
         |
         +--ExternalLibraryFunction

Package:
stx:libbasic
Category:
System-Support
Version:
rev: 1.31 date: 2017/03/03 15:21:23
user: cg
file: ExternalFunction.st directory: libbasic
module: stx stc-classLibrary: libbasic
Author:
Claus Gittinger

Description:


Instances of this class represent external (non-Smalltalk) functions.

(Obsolete) Custom Functions:
    This class also provides access to custom functions.
    These custom functions enable you to call c functions
    even if no stc compiler is available (they are kind of what user-primitives are in ST-80).
    You can register your own custom C-functions in a private main.c and relink ST/X from the binaries.
    (see the demo functions provided in main.c).
    Notice, that custom functions are ugly and inflexible.
    They are to be considered obsolete and support for them will vanish.

If you have the stc compiler, we recommend using either inline primitive
code or the new external function call interface which is based upon libffi.
Both are easier to enter, compile, debug and maintain.
(especially, to maintain, since the primitive code is contained
 in the classes source/object file - while custom functions are
 external to the classLibraries).

Non custom externalFunctions are created, when a non-ST shared library is loaded,
and returned by the ObjectFileHandles>>getFunction: method.

The C functions contained in that lib are callable (instances of myself)
with the call / callWith: methods.

ST-arguments are converted to C as follows:
    ST class            C argument
    ------------------------------
    SmallInteger        int
    LargeInteger        int (must be 4-byte unsigned largeInteger)
    String              char *
    Symbol              char *
    Character           int
    ExternalBytes       char *
    ExternalAddress     char *
    ExternalFunction    char *
    FloatArray          float *
    DoubleArray         double *
    ByteArray           char *
    ShortFloat          float
    true                1
    false               0

The returned value is converted to an unsigned integer (smallInteger or largeInteger).

Notice, that no doubles can be passed; the reason is that the calling
conventions (on stack, in registers, in FPU registers etc.) are so different among
machines (and even compilers), that a general solution is not possible (difficult)
to program here. To pass doubles, either use shortFloats, or pack them into a DoubleArray.
For functions with up to 2 double arguments, specialized call methods are provided.
Sorry for that inconvenience.


- This is still in construction and NOT yet published for
  general use. For now, use inline C-code.


Related information:

    ExternalAddress
    ExternalBytes
    [how to write primitive code]

Class protocol:

Signal constants
o  invalidCustomFunctionSignal
return the signal raised when a non existent custom function is
called for.

calling custom functions
o  callCustomFunction: nr
call the custom function #nr without arguments.
See main.c for examples.
usage example(s):
     ExternalFunction callCustomFunction:0
     ExternalFunction callCustomFunction:999

o  callCustomFunction: nr with: arg
call the custom function #nr with a single argument.
See main.c for examples.
usage example(s):
     ExternalFunction callCustomFunction:1 with:'hello world'

o  callCustomFunction: nr with: arg1 with: arg2
call the custom function #nr with two arguments.
See main.c for examples.
usage example(s):
     ExternalFunction callCustomFunction:2 with:(Float pi) with:1.0

o  callCustomFunction: nr with: arg1 with: arg2 with: arg3
call the custom function #nr with three arguments.
See main.c for examples.

o  callCustomFunction: nr withArguments: argArray
call the custom function #nr with arguments from argArray.
See main.c for examples.
usage example(s):
     ExternalFunction callCustomFunction:2 withArguments:#(1.0 1.0)
     ExternalFunction callCustomFunction:999 withArguments:#(1.0 1.0)

o  callCustomFunctionNamed: name withArguments: argArray
call a custom function by name with arguments from argArray
usage example(s):
     ExternalFunction callCustomFunctionNamed:'demoFunction0'
				withArguments:#()

o  indexOfCustomFunctionNamed: functionName
return the index of a named custom function
usage example(s):
     ExternalFunction indexOfCustomFunctionNamed:'demoFunction0'
     ExternalFunction indexOfCustomFunctionNamed:'fooBar'

initialization
o  initialize
create signals

queries
o  isBuiltInClass
return true if this class is known by the run-time-system.
Here, true is returned for myself, false for subclasses.


Instance protocol:

accessing
o  moduleHandle
return the function's moduleHandle
(nil if not loaded dynamically)

o  name
return the function's name

function calling
o  call
call the underlying C function, passing no argument.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callByRefWith: arg
call the underlying C function, passing a single argument by reference.
The pointer of the argument is passed. Use this if you want to call a
function with call-by-refernece semantics, like in fortran.
The argument arg is converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callByRefWith: arg with: arg2
call the underlying C function, passing two args.
The pointer of the arguments are passed. Use this if you want to call a
function with call-by-refernece semantics, like in fortran.
The arguments are converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callByRefWith: arg with: arg2 with: arg3
call the underlying C function, passing three args.
The pointer of the arguments are passed. Use this if you want to call a
function with call-by-refernece semantics, like in fortran.
The arguments are converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callByRefWithArguments: argArray
call the underlying C function, passing up to 10 arguments by reference.
The arguments are converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callO
call the underlying C function, passing no argument.
The return value must be a valid object.

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callOWith: arg
call the underlying C function, passing a single object argument.
The return value must be a valid object.

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callOWith: arg1 with: arg2
call the underlying C function, passing two args.
The return value must be a valid object.

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callOWith: arg1 with: arg2 with: arg3
call the underlying C function, passing three args.
The return value must be a valid object.

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callWith: arg
call the underlying C function, passing a single argument.
The argument arg is converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callWith: arg1 with: arg2
call the underlying C function, passing two args.
The arguments are converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callWith: arg1 with: arg2 with: arg3
call the underlying C function, passing three args.
The arguments are converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callWithArguments: argArray
call the underlying C function, passing up to 10 arguments.
The arguments are converted to a corresponding C data type,
as defined in the convertST_to_C() function.
The return value is interpreted as an integer
(and must be converted to an externalBytes object,
if it is a pointer to something).

DANGER alert: This is an unprotected low-level entry.
Not for normal application usage.

o  callWithDouble: aFloatArg returnsDouble: doubleFlag
call the underlying C function, passing a single double argument.
The returnsDouble flag specifies if the returnValue is a double; if false,
an integer returnValue is assumed.

o  callWithDouble: aFloatArg1 withDouble: aFloatArg2 returnsDouble: doubleFlag
call the underlying C function, passing two double arguments.
The returnsDouble flag specifies if the returnValue is a double; if false,
an integer returnValue is assumed.

printing & storing
o  printOn: aStream
append a printed representation of the receiver to aStream

private-loader access
o  invalidate

o  setModuleHandle: aHandle
set the moduleHandle.
This is a private interface for the objectFileLoader; not for public use.

o  setName: aString moduleHandle: aHandle
set the name & moduleHandle.
This is a private interface for the objectFileLoader; not for public use.


Examples:


see a sample demo c file in doc/coding/cModules; compile and link (shared) it to an object module. Load it into the system: handle := ObjectFileLoader loadDynamicObject:'demo1.o'. get a C-function (an instance of ExternalFunction): f := handle getFunction:'function1'. call it: f callWith:999

ST/X 7.1.0.0; WebServer 1.663 at exept.de:8081; Sun, 23 Sep 2018 10:12:25 GMT