External types

todo: describe what actually IS implemented and update Externals

The syntax will have to be flexible enough to work for any reasonable external language, not just C (e.g. Java). No provision is made for embedding variable-sized external types.

The plug-in for the examples

For syntactic experiments, we'll assume the following C files are used.

my_struct.h:

typedef struct {
  double x;
  int c;
} my_struct;

my_struct.c:

#include "my_struct.h"
use (my_struct *x) {
  x->x = 3.14;

  if(x->c == 0) x->c = 5;
  else          x->c++;

  printf("x = %f, c = %d\n", x->x, x->c);
}

use_copy (my_struct x) {
  x.x = 3.14;

  if(x.c == 0) x.c = 5;
  else         x.c++;

  printf("x = %f, c = %d\n", x.x, x.c);
}

The program should print

x = 3.14, c = 5
x = 3.14, c = 6

Embedding external types in Liberty Eiffel

There are currently two competing mechanisms. Their expressivity is roughly the same (when you have one it is easy to emulate the other).

External attributes

The "external" keyword is used as a type name to tell the Eiffel compiler that an attribute should be represented by a user-specified external type. (The precise syntax is not fixed: the attribute may look better with a "plug_in" manifest string or an "is" keyword)

class SHOW

creation
    make

feature
   make is
      do
         use($ext)
         use_copy(ext)
      end

   use (x: POINTER) is
      external "plug_in"
      alias "{
         location: "./"
         module_name: "struct"
         feature_name: "use"
         }"
      end

   use_copy (x: like ext) is
      external "plug_in"
      alias "{
         location: "./"
         module_name: "struct"
         feature_name: "use_copy"
         }"
      end

   ext: external
      alias "{
         location: "./"
         module_name: "struct"
         attribute_type: "my_struct"
         }"
      end
end

External classes

A special marker is used to tell the Eiffel compile that a class should be represented by a user-specified external type. Methods of that class can be implemented by passing Current as a parameter to external routines. Whether Current is passed by copy or by reference could be determined by the reference/expanded status of the external class.

Issues:

• Forces the programmer to write one class for each external type they want to wrap

expanded class SHOW

external "plug_in"
   alias "{
      location: "./"
      module_name: "struct"
      attribute_type: "my_struct"
      }"

creation
    make

feature
    make is
        do
            -- Memory is zeroed, so we probably don't need to initialize x and
            -- c. If we do, we'll have to call a C function to do it.
            use($Current)
            use_copy(Current)
        end

    use (x: POINTER) is
        external "plug_in"
        alias "{
            location: "./"
            module_name: "struct"
            feature_name: "use"
            }"
        end

   use_copy (x: like Current) is
      external "plug_in"
      alias "{
         location: "./"
         module_name: "struct"
         feature_name: "use_copy"
         }"
      end

end

Two variants (along with possible hybrids)

Living at the edge of the Eiffel world

• External classes always insert exactly ANY (and don't inherit from anything)
• they can't be inherited from (and probably not inserted either)
• they can't have ordinary Eiffel attributes.

Ordinary Eiffel citizens

• External classes can have Eiffel attributes
• External classes can be inherited from and inserted
• External classes ca, inherit from or insert other classes

Likely to result in a very unclean implementation (need either to reorder the struct so that the external part is at the beginning, or to represent references to such objects as pointers 'into' the object (rather than to its head), or to mess with the pointer when passing it to the C world). Even more mess likely in case of multiple external parents.

Inline external classes

Ok, so there are actually three mechanisms, but this one is hybrid between the previous two (give the external attribute an Eiffel type that doesn't need to be defined anywhere else)

With this approach we can even allow this type for external features, which would solve the pass-by-value/reference question: do a copy or use a pointer to it.

Issues:

• What is the scope of such a type? Only visible in the class it is written in? Are two external types with the same "name" in different classes the same?

class SHOW
creation
   make

feature
   make is
      do
         use($ext)
         copy_use(ext)
      end

   use (x: POINTER) is
      external "plug_in"
      alias "{
         location: "./"
         module_name: "struct"
         feature_name: "use"
         }"
      end

  use_copy (x: like ext) is
         -- Here a copy of x would be passed
      external "plug_in"
      alias "{
         location: "./"
         module_name: "struct"
         feature_name: "use_copy"
         }"
      end

   ext: external MY_STRUCT is  -- inline declaration of external type
      external "plug_in"
      alias "{
         location: "./"
         module_name: "struct"
         attribute_type: "my_struct"
         }"
      end
end

Helper functions

It must be possible for plugin writer to supply functions to help the Liberty Eiffel runtime implement a few of ANY's standard routines: standard_copy, deep_twin, standard_is_equal, deep_is_equal.

Optional vs. mandatory helpers

Putting helpers could be made mandatory or optional (if a reasonable default can be found).

Provide defaults where possible

A reasonable default is to assume that the external types are shallow, so the helpers for deep_twin and deep_is_equal can be made optional (but the plugin writer can provide them if he wants a special treatment)

Some backends may also be able to provide reasonable default helpers for standard_is_equal and standard_copy, making them optional. For other backends, the plugin-writer may have to provide one or both of the helpers. That may seem inconsistent but it's not really a problem as a plugin needs to be tested with every back-end it is supposed to work with anyway, so missing helpers will be detected. The C backend can generate a default copy function (using memcpy and sizeof), but it can't genereate a default equality testing function (the == operator can't be applied to structures, memcmp is unacceptable because two structures may differ only by garbage in the padding).

Don't provide defaults at all

Just throw an error if one of the helpers is missing.

Provide silly defaults, emit a warning

The default helpers just crash (with a run time stack if possible). Emit a warning if the plugin writer doesn't provide the required helpers.

Granularity

The granularity could be one pack of helpers per Eiffel class or one pack of helpers per external type (obvisouly there's no difference if the "external classes" implementation is chosen).

Eiffel class granularity

The helpers are eiffel functions with "magical" names.

External type granularity

The helper's names appear inside the "alias" clause.

Relevance to backends

Depending on the backend, the mechanism can add real expressivity or be of the "sugar" variety.

C

This is the only way to embed C structures into Eiffel objects. It also makes it easier to interact with C types that are typedef'd or #defined to a basic type that is not known in advance (up to now, plugin-writers had to guess if it would be e.g. an INTEGER_32 or an INTEGER_64).

Java

All the basic types are already wrapped and there are no typedefs or #defines. Finally, it is not possible to embed Java objects, so the gain would be limited. At least it means that we could rewrite the wrappers for the basic types using external types if we had the time (less magic is always a good thing!), and the we can embed more precise references to java objects than just "Object".