The Melange Interface Generator

define interface
   #include "const.h";

   constant "MAXINT" => $maximum-fixed-integer,

      value: 9999999;
end interface;

13. Variable Clauses

Global variables declared within C header files are translated into "getter" functions which retrieve the value of the C variables and optional "setter" functions to modify those values. In effect, they are treated as slots of a "null object" --the getter function takes no arguments and returns the value of the variable, while the setter function takes a single value which will be the new value of the variable. Type mapping takes place for the arguments and results of these functions, just as it would for slot accessors.

Variable clauses support the following options:

• getter: -- specifies a Dylan variable name which will be used to hold the getter function.
• setter: -- specifies either a Dylan variable name which will be used to hold the setter function, or #f to indicate that there should be no setter function.
• read-only: -- specifies whether the variable should be settable. "read-only: #t" is equivalent to "setter: #f".
• seal: -- specifies whether the getter and setter functions should be sealed. Possible values are "sealed" or "open", and the default is taken from the "seal-functions:" option in the "#include" clause (or "sealed" if not specified there).
• map: -- specifies the high-level type to which the variable should be mapped.
• equate: -- specifies the low-level type to which the raw C value should be implicitly converted.

Appendix I --

Low level support facilities

The high level functions for calling C routines or for accessing global variables are all built upon a relatively small number of built-in primitives which perform specific low-level tasks. You should seldom have any need to deal with these primitives directly, but they are nonetheless available should you need to make use of them.

To use these types and operations, you should "use" the module "extern" from the "Dylan" library.

I.i. Predefined types

<statically-typed-pointer> [class]

Unless otherwise specified, C pointers are implicitly "equated" to newly created subclasses of <statically-typed-pointer>. This class is contains a single implicit slot which contains the raw C pointer. Because of implementation limitations in Mindy, you may not add any extra slots to subclasses of <statically-typed-pointer>, nor can such a subclass inherit slots from other classes. You may, however, create classes which are subclasses of both <statically-typed-pointer> and other (presumably abstract) classes which have no slots.

The "make" method for takes three keywords. The "pointer:" keyword tells it to initialize the new variable with the given value, which must be a <statically-typed-pointer> or an <integer>. If the no pointer value is specified, space will be allocated based upon the content-size of the specific type and upon the "extra-bytes:" and "element-count:" keywords. These keywords, which default to "0" and "1" respectively, tell how many objects are going to be stored in the memory and how many bytes of extra memory (beyond that specified by "content-size") should be allocated for each element.

<c-vector> [class]

<C-vector> is a subclass of <statically-typed-pointer> which inherits operations from <vector>. Because systems often depend upon C’s lack of bounds checking, the default size for <c-vector>s is "#f". However, subclasses of <c-vector> may provide a concrete size if desired. Types corresponding to declarations such as "char [256]" are automatically declared as subclasses of <c-vector>, but pointer declarations such as "char *" are not.

<c-string> [class]

<C-string> is a subclass of <statically-typed-pointer> which also inherits operations from <string>. It is implemented as a C pointer to a null-terminated vector of characters, and provides a method on forward-iteration-protocol which understands this implementation. This class may, therefore, be used for manipulating C’s native format for "string"s (i.e. "char *"). Note that the "null" string is considered to be a valid empty string. This is somewhat contrary to the semantics of many C operations, but provides a safer model for Dylan code.

The "make" method for <c-string>s accepts the "size:" and "fill:" keywords.

There are a few surprising properties of <c-strings> which may users should be aware of, both of which result from the "null-terminated" implementation. Firstly, the "size" of the string is computed by counting from the beginning of the string, and is therefore not nearly as efficient as you might expect. Secondly, you should expect odd results if you try to store "as(<character>, 0)" into such a string. Finally, the "element" and "element-setter" methods must scan the string in order to do bounds checking, and may therefore be fairly slow. If you wish to (unsafely) bypass this checking, you must use "pointer-value" instead.

<c-function> [class]

<c-function>s, like <statically-typed-pointer>s, encapsulate a raw "C" pointer. However, <c-function>s also encode information about the calling conventions of the function which is (presumably) located at the given address. They may, therefore, be directly invoked just like any other function.

<foreign-file> [class]

The <foreign-file> class is used to store information about the contents of a particular object file. It is created by "load-object-file", and may be passed as an option to "find-c-function" and "find-c-pointer". (All of these functions are described below.)

I.ii. Locating native C objects

There are several functions provided which search for C functions or variables and return Dylan objects which refer to them. Note that Mindy does not have sufficient information to determine whether any given C object is a function, and therefore it depends upon the user (or, more often, Melange) to provide it with correct information.

load-object-file(files :: <list>, #key symbols) [function]

This function (which is presently only works on HPUX machines) attempts to dynamically load a given object file (i.e. ".o" or ".a") into the current Mindy process and load it’s symbol table to allow its contents to be located by "find-c-pointer" or "find-c-function". If it successfully loads the file, it will return a <foreign-file> encapsulating the symbol table information. Otherwise, it will return #f.

If you are not running on an HPUX machine, you will have to statically link object files into Mindy, as described in Appendix II.

find-c-pointer(name :: string, #key file :: <foreign-file) [function]

This function searches through the symbol table for the object file corresponding to the specified file (or for Mindy itself) and attempts to locate a symbol with the given name. If it finds such a symbol, it converts the corresponding address to a <statically-typed-pointer> and returns it. Otherwise, it returns #f.

find-c-function (name :: <string>, #key file) [function]

constrain-c-function (fun :: <c-function>, [function]

specializer :: <list>, rest? :: <boolean>,

results :: <list>)

The function "find-c-function" is like "find-c-pointer", except that the result is a <c-function> (or #f). The resulting function is specialized to "fun(#rest args) :: <object>". However, it may be constrained to a different set of specializers via "constrain-c-function". This function accepts lists of types for the arguments and for the return values, and a boolean value which states whether optional arguments are accepted. The result declarations are particularly important, since they are used to coerce the raw C result value into an appropriate low level Dylan type. The possible types are <boolean>, <integer>, or any subclass of <statically-typed-pointer>. Note that although a list of result types is accepted, only the first can be meaningful since C does not support multiple return values.

Note: The functions in this section are likely to change drastically in the near future.

I.iii. Pointer manipulation operations

Each <statically-typed-pointer> encapsulates a pointer to some area of memory (i.e. a raw machine address). In itself, this does little good, except as an arbitrary token. However, Mindy provides a number of primitive operations which manipulate the contents of these addresses, or do basic comparisons and arithmetic upon the addresses themselves.

signed-byte-at (ptr :: <statically-typed-pointer>, #key offset) [function]

unsigned-byte-at (ptr :: <statically-typed-pointer>, #key offset) [function]

signed-short-at (ptr :: <statically-typed-pointer>, #key offset) [function]

unsigned-short-at( ptr :: <statically-typed-pointer>, #key offset) [function]

signed-long-at (ptr :: <statically-typed-pointer>, #key offset) [function]

unsigned-long-at (ptr :: <statically-typed-pointer>, #key offset) [function]

pointer-at (ptr :: <statically-typed-pointer>, [function]

#key offset, class)

These operations return an object which represents the value stored at the address corresponding to "ptr". The first six operations all return <integer>s -- the different versions are required because the same number may be represented in a variety of formats (differing in length and interpretation of the high-order bit) and because Mindy has no way of determining which might be used in a given situation. The final operation, "pointer-at", returns a new <statically-typed-pointer> encapsulating the address referenced by the origninal pointer. You may use the "class:" keyword to specify that the new object should be an instance of some particular subclass of <statically-typed-pointer>. (Thus, for example "pointer-at(foo, class: <bar>)" would be roughly equivalent to "as(<bar>, pointer-at(foo))".)

The offset parameter (if provided) is added to the integer corresponding to the machine address before the pointer is dereferenced. This is useful, for example, in loading an object from within a C "struct".

Setter functions are provided corresponding to each of the above functions. You can therefore, say

signed-short-at(ptr) := 32767;
pointer-at(ptr1) := ptr2;

as(cls == <integer>, ptr :: <statically-typed-pointer>) [G.F. Method]

as(cls == <statically-typed-pointer>, ptr :: <statically-typed-pointer>)

[G.F. Method]

as(cls == <statically-typed-pointer>, int:: <integer>) [G.F. Method]

Method upon "as" are provided for converting from <integer> to any statically typed pointer class and from any statically typed pointer class to <integer> or to another statically typed pointer class.

\+ (ptr :: <statically-typed-pointer>, int :: <integer>) [G.F. Method]

\- (ptr1 :: <statically-typed-pointer, ptr2 :: <statically-typed-pointer>)

[G.F. Method]

\= (ptr1 :: <statically-typed-pointer, ptr2 :: <statically-typed-pointer>)

[G.F. Method]

These functions do arithmetic upon the integers corresponding to the given pointers. The following code fragment

let new-ptr = ptr1 + 3;
let difference = ptr2 + ptr3;
let same? = (ptr2 = ptr3)

is equivalent to

let new-ptr = as(ptr1.object-class, as(<integer>, ptr1) + 3);
let difference = as(<integer>, ptr2) - as(<integer>, ptr3);
let same = (as(<integer>, ptr2) = as(<integer>, ptr3));

Appendix II --

Static linking mechanisms

Because object file formats vary widely by architecture, Mindy does not support dynamic loading of object files or automatic symbol table look up for all architectures. In the general case, it is necessary to depend upon a less elegant technique for explicitly making certain C objects available.

Simple instructions for using this mechanism from within Melange are given in section 3.1. This appendix simply provides more information on the underlying mechanism.

In order to make sure that the desired symbols can be located, it is necessary to build an explicit table which maps between the symbol’s name and its address. This table is automatically created by running the "make-init.pl" script [This requires you to have PERL installed on your system.] upon a list of "interface definition files". This will create two files ",extern1.def" and ",extern2.def", which should then be renamed to "extern1.def" and "extern2.def" respectively. These files are automatically included by "ext-init.c" so that the table will be created after Mindy is rebuilt.

The interface definition files consist of zero or more lines of text, each of which should contain the name of one object. If the object is a function, it should be immediately followed by a set of parentheses. For example, the file which defines the memory allocation routines used by Melange’s support code contains the following four lines:

free()
malloc()
strcmp()
strlen()

define interface date
   #include "date.h";
   use time, import: {"struct time"};
end interface date;

define interface
   #include "date.h",
      interface-name: "date";
end interface;

define interface
   #include "dirent.h",

      equate: {"char *" => <c-string>},

      map: {"char *" => <byte-string>};
end interface;

define interface
   #include "dirent.h",
      equate-and-map: {"char *" => <c-string> => <byte-string>};
end interface;

define interface
   #include "dirent.h";
   transform "char *",

      low-level: <c-string>,
      high-level: <byte-string>;
end interface;