Understanding Ewg

Functions

This section describes what code gets generated for a C function declaration and how to use that code to call the declared function.

Let us look at the following function declaration (taken from the simple-example)

	   
int func2 (int a, int b);
	   
	 

func2 is a function that takes two parameters of type int and returns a value of type int. EWG generates an Eiffel wrapper class for it in the cluster eiffel\external\function:

class SIMPLE_HEADER_FUNCTIONS_EXTERNAL

feature

	func2_external (a: INTEGER; b: INTEGER) : INTEGER

	get_func2_pointer_external: POINTER

end
	 

The name of the class is SIMPLE_HEADER_FUNCTIONS_EXTERNAL. This is because the function declaration comes from the C header file simple_header.h. EWG will put all function declarations from the same header in the same class.

func2_external is the routine you will want to call if you want to execute the c function func2. get_func2_pointer_external gives you the address of the C function. You need the address of an function if you want to pass it as a callback for example.

For functions only low-level wrappers are generated.

Structs

This section describes what code gets generated for a C struct declaration and how to use that code to create, free, read from and write to a struct.

Enums

This section describes what code gets generated for a C enum declaration and how to use that code.

Let us look at the following enum declaration (taken from the simple-example)

	   
typedef enum
{
	red,
	blue,
	green
} colors;
	   
	 

colors is an alias for an anonymous enum. EWG generates an Eiffel wrapper class for it in the cluster eiffel\external\enum:

	   
class interface COLORS_ENUM_EXTERNAL

feature(s) from COLORS_ENUM_EXTERNAL

	red: INTEGER

	blue: INTEGER

	green: INTEGER

end of COLORS_ENUM_EXTERNAL
	   
	 

The name of the class is COLORS_ENUM_EXTERNAL. Since Eiffel does not have the enum concept, enums are mapped as INTEGER constants in Eiffel. Simply inherit from COLORS_ENUM_EXTERNAL wherever you want to use them.

Callbacks

This section describes what code gets generated for C callbacks and how to use that code. Now first of all its not as trivial to define what a callback is. EWG defines callbacks as pointers to functions. Wherever it sees a pointer to a function, it generates a callback wrapper. Of course chances are some pointers to functions are not meant to be callbacks, but in this case we can simply ignore the generated code.

It is important to understand that there is an inherent problem when wrapping callbacks in Eiffel. For example the following callback:

	   
			 typedef void (*void_callback) (void);
	   
	 

Does not convey any state when invoked (other than it has been invoked). This is the reason for the following limitation: One can only register one Eiffel callback receiver per callback type. If more receivers were allowed how would one decide on the invocation of a callback which receiver is meant? In practice this limitation is usually of no concern. Most C libraries have adopted a pseudo OO technique of supplying a user definable parameter as the first parameter on every callback. This parameter can be used to do further dispatching. Have a look a the GTK or OpenGL examples to see how to do this.

A solution to overcome this limitation using dynamic function generation is being worked on.

Let us look at the following declarations (taken from the callback-example)

	   
typedef void (*sample_callback_type) (void* pdata, int a_event_type);

// make `sample_callback_type' receive events.
void register_callback (sample_callback_type a_callback, void* pdata);

// make all registered callbacks receive an event
void trigger_event (int a_event_type);
	   
	 

sample_callback_type is the actual callback. register_callback is used to register a given callback receiver, so that it gets called whenever one calls trigger_event. The two function declarations are wrapped as usual. For sample_callback_type EWG generates two classes. Both are located in eiffel\abstraction\callback. Actually EWG generates lower level classes two, even special C code, but these are omitted here. The two classes of interest are SAMPLE_CALLBACK_TYPE_DISPATCHER and SAMPLE_CALLBACK_TYPE_CALLBACK. The first one is the singleton that you have to create in order to establish the C-Eiffel bridge. Use SAMPLE_CALLBACK_TYPE_DISPATCHER.c_dispatcher whenever you need to provide the C side with a pointer to the callback receiver. The creation routine of SAMPLE_CALLBACK_TYPE_DISPATCHER expects an object of type SAMPLE_CALLBACK_TYPE_CALLBACK. Create your own callback receiver class let it inherit from SAMPLE_CALLBACK_TYPE_DISPATCHER and use an object of your new class for the creation routine argument. Here are the interfaces of the generated classes:

	   
class interface SAMPLE_CALLBACK_TYPE_DISPATCHER

create

	make (a_callback: SAMPLE_CALLBACK_TYPE_CALLBACK)
		require
		 a_callback_not_void: a_callback /= Void

feature(s) from SAMPLE_CALLBACK_TYPE_DISPATCHER

	callback: SAMPLE_CALLBACK_TYPE_CALLBACK

	c_dispatcher: POINTER

invariant

	callback_not_void: callback /= Void;

end of SAMPLE_CALLBACK_TYPE_DISPATCHER
	   
	 

	   
deferred class interface SAMPLE_CALLBACK_TYPE_CALLBACK

feature(s) {SAMPLE_CALLBACK_TYPE_DISPATCHER} from SAMPLE_CALLBACK_TYPE_CALLBACK

	on_callback (a_pdata: POINTER; a_a_event_type: INTEGER)

end of deferred SAMPLE_CALLBACK_TYPE_CALLBACK
	   
	 

Assuming that you have created a class MY_CALLBACK_RECEIVER which inherits from SAMPLE_CALLBACK_TYPE_CALLBACK, the following code demonstrates the use of callbacks

	   
feature

	make is
		do
			 -- Establish the C<->Eiffel bridge.
		  -- From now on, whenever `trigger_event_external' gets called
		  -- `MY_CALLBACK_RECEIVER.on_callback' gets called too.
		  register_callback_external (dispatcher.c_dispatcher)
		end

	dispatcher: SAMPLE_CALLBACK_TYPE_DISPATCHER is
		local
		 my_callback_receiver: MY_CALLBACK_RECEIVER
		once
		 create my_callback_receiver.make
		 create Result.make (my_callback_receiver)
		end

	trigger is
		do
		 trigger_event_external
		 -- `MY_CALLBACK_RECEIVER.on_callback' has now been called
		end
	   
	 

Pointers

EWG provides a class called EWG_MANAGED_POINTER (it is very similar and actually inspired by ISEs MANAGED_POINTER class). This class encapsulates C memory areas on a higher level than the kernel class POINTER. TODO: continue

Wrapper Objects

It is important to know that instances of C structs, unions or really any C memory area are by default not first class Eiffel objects. Instead EWG creates classes who's instances can serve as companion objects. For example let's look at the following struct:

	   
struct person
{
	char* first_name;
	char* last_name;
	char* phone_number;
};
	   
	 

For this struct EWG will create a class EWG_PERSON_STRUCT_EXTERNAL, which provides low level and non-object-oriented access to the struct. EWG will also create a class called EWG_PERSON_STRUCT which uses the former class to provide the companion objects. In the next figure you can see how the relate.

The Eiffel wrapper object really only stores a reference (item) to the C struct instance. When you invoke person.first_name, where person is of type PERSON_STRUCT then the actual data will be retrieved from the C struct instance being referenced via item.

Wrapper Modes

Wrappers based on pointers (EWG_MANAGED_POINTER, EWG_STRUCT and EWG_UNION) can be created to be shared or unshared, new or existing via one of the following creation procedures:

• make_shared
• make_unshared
• make_new_shared
• make_new_unshared

Dependent Types

If you choose to include a type who depends on a type which you choose to exclude, the dependent type will also be included. Confused? Let's say you have:

	   
struct foo
{
	int i;
};
struct bar
{
	struct foo* pfoo;
};
	   
	 

And you specify the following config file:

	   
			 <?xml version="1.0"?>
			 <ewg_config>

<rule_list>
<rule>
<match>
<identifier name="bar"/>
</match>
<wrapper type="default">
</wrapper>
</rule>

<rule>
<match>
</match>
<wrapper type="none">
</wrapper>
</rule>
</rule_list>

</ewg_config>
	   
	 

That would mean, struct bar will be wrapped and struct foo will not be wrapped. Now, because struct bar depends on struct foo, struct bar will be wrapped after all.