| Online Eiffel Documentation

EiffelStudio

# 10 Other Mechanisms

We now examine a few important mechanisms that complement the preceding picture: shared objects; constants; instructions; and lexical conventions.

## Once routines and shared objects

The Eiffel's method obsession with extendibility, reusability and maintainability yields, as has been seen, modular and decentralized architectures, where inter-module coupling is limited to the strictly necessary, interfaces are clearly delimited, and all the temptations to introduce obscure dependencies, in particular global variables, have been removed. There is a need, however, to let various components of a system access common objects, without requiring their routines to pass these objects around as arguments (which would only be slightly better than global variables). For example various classes may need to perform output to a common "console window", represented by a shared object.

Eiffel addresses this need through an original mechanism that also takes care of another important issue, poorly addressed by many design and programming approaches: initialization. The idea is simple: if instead of do the implementation of an effective routine starts with the keyword once , it will only be executed the first time the routine is called during a system execution (or, in a multi-threaded environment, the first time in each thread), regardless of what the caller was. Subsequent calls from the same caller or others will have no effect; if the routine is a function, it will always return the result computed by the first call -- object if an expanded type, reference otherwise.

In the case of procedures, this provides a convenient initialization mechanism. A delicate problem in the absence of a once mechanism is how to provide the users of a library with a set of routines which they can call in any order, but which all need, to function properly, the guarantee that some context had been properly set up. Asking the library clients to precede the first call with a call to an initialization procedure setup is not only user-unfriendly but silly: in a well-engineered system we will want to check proper set-up in every of the routines, and report an error if necessary; but then if we were able to detect improper set-up we might as well shut up and set up ourselves (by calling setup ). This is not easy, however, since the object on which we call setup must itself be properly initialized, so we are only pushing the problem further. Making setup a once procedure solves it: we can simply include a call

    setup

at the beginning of each affected routine; the first one to come in will perform the needed initializations; subsequent calls will have, as desired, no effect.

Once functions will give us shared objects. A common scheme is

    console: WINDOW is
    		-- Shared console window
    	once
    		create Result.make (...)
    	end

Whatever client first calls this function will create the appropriate window and return a reference to it. Subsequent calls, from anywhere in the system, will return that same reference. The simplest way to make this function available to a set of classes is to include it in a class SHARED_STRUCTURES which the classes needing a set of related shared objects will simply inherit.

For the classes using it, console , although a function, looks very much as if it were an attribute -- only one referring to a shared object.

The "Hello World" system at the beginning of this discussion (section 4) used an output instruction of the form io . put_string ( Some string ) . This is another example of the general scheme illustrated by console . Feature io , declared in ANY and hence usable by all classes, is a once function that returns an object of type STANDARD_FILES (another Kernel Library class) providing access to basic input and output features, one of which is procedure put_string . Because basic input and output must all work on the same files, io should clearly be a once function, shared by all classes that need these mechanisms.

## Constant and unique attributes

The attributes studied earlier were variable: each represents a field present in each instance of the class and changeable by its routines.

It is also possible to declare constant attributes, as in

    Solar_system_planet_count: INTEGER is 9

These will have the same value for every instance and hence do not need to occupy any space in objects at execution time. (In other approaches similar needs would be addressed by symbolic constants, as in Pascal or Ada, or macros, as in C.)

What comes after the is is a manifest constant: a self-denoting value of the appropriate type. Manifest constants are available for integers, reals (also used for doubles), booleans ( True and False ), characters (in single quotes, as 'A' , with special characters expressed using a percent sign as in '%N' for new line, '%B' for backspace and '%U' for null).

For integer constants, it is also possible to avoid specifying the values. A declaration of the form

    a, b, c, ... n : INTEGER is unique

introduces a , b , c , ... n as constant integer attributes, whose value are assigned by the Eiffel compiler rather than explicitly by the programmer. The values are different for all unique attributes in a system; they are all positive, and, in a single declaration such as the above, guaranteed to be consecutive (so that you may use an invariant property of the form code > a and code < n to express that code should be one of the values). This mechanism replaces the "enumerated types" found in many languages, without suffering from the same problems. (Enumerated types have an ill-defined place in the type system; and it is not clear what operations are permitted.)

You may use Unique values in conjunction with the inspect multi-branch instruction studied in the next section. They are only appropriate for codes that can take on a fixed number of well-defined values -- not as a way to program operations with many variants, a need better addressed by the object-oriented technique studied earlier and relying on inheritance, polymorphism, redeclaration and dynamic binding.

Manifest constants are also available for strings, using double quotes as in

    User_friendly_error_message: STRING is "Go get a life !"

with special characters again using the % codes. It is also possible to declare manifest arrays using double angle brackets:

    <<1, 2, 3, 5, 7, 11, 13, 17, 19>>

which is an expression of type ARRAY [INTEGER] . Manifest arrays and strings are not atomic, but denote instances of the Kernel Library classes STRING and ARRAY , as can be produced by once functions.

## Instructions

Eiffel has a remarkably small set of instructions. The basic computational instructions have been seen: creation, assignment, assignment attempt, procedure call, retry. They are complemented by control structures: conditional, multi-branch, loop, as well as debug and check.

A conditional instruction has the form if ... then ... elseif ... then ... else ... end . The elseif ... then ... part (of which there may be more than one) and the else ... part are optional. After if and elseif comes a boolean expression; after then , elseif and else come zero or more instructions.

A multi-branch instruction has the form

    inspect
    	exp
    when v1 then
    	inst1
    when v2 then
    	inst2
    ...
    else
    	inst0
    end

where the else inst0 part is optional, exp is a character or integer expression, v1, v1, ... are constant values of the same type as exp , all different, and inst0, inst1, inst2, ... are sequences of zero or more instructions. In the integer case, it is often convenient to use unique values ("Constant and unique attributes", page 83) for the vi

The effect of such a multi-branch instruction, if the value of exp is one of the vi, is to execute the corresponding insti. If none of the vi matches, the instruction executes inst0, unless there is no else part, in which case it triggers an exception.

Raising an exception is the proper behavior, since the absence of an else indicates that the author asserts that one of the values will match. If you want an instruction that does nothing in this case, rather than cause an exception, use an else part with an empty inst0. In contrast, if c then inst end with no else part does nothing in the absence of an else part, since in this case there is no implied claim that c must hold.

The loop construct has the form

    from
    	initialization
    until
    	exit
    invariant
    	inv
    variant
    	var
    loop
    	body
    end

where the invariant inv and variant var parts are optional, the others required. initialization and body are sequences of zero or more instructions; exit and inv are boolean expressions (more precisely, inv is an assertion); var is an integer expression.

The effect is to execute initialization, then, zero or more times until exit is satisfied, to execute body. (If after initialization the value of exit is already true, body will not be executed at all.) Note that the syntax of loops always includes an initialization, as most loops require some preparation. If not, just leave initialization> empty, while including the from since it is a required component.

The assertion inv, if present, expresses a loop invariant (not to be confused with class invariants). For the loop to be correct, initialization must ensure inv, and then every iteration of body executed when exit is false must preserve the invariant; so the effect of the loop is to yield a state in which both inv and exit are true. The loop must terminate after a finite number of iterations, of course; this can be guaranteed by using a loop variant var. It must be an integer expression whose value is non-negative after execution of initialization, and decreased by at least one, while remain non-negative, by any execution of body when exit is false; since a non-negative integer cannot be decreased forever, this ensures termination. The assertion monitoring mode, if turned on at the highest level, will check these properties of the invariant and variant after initialization and after each loop iteration, triggering an exception if the invariant does not hold or the variant is negative or does not decrease.

An occasionally useful instruction is debug ( Debug_key, ... ) instructions end where instructions is a sequence of zero or more instructions and the part in parentheses is optional, containing if present one or more strings, called debug keys. The EiffelStudio compiler lets you specify the corresponding debug compilation option: yes , no , or an explicit debug key. The instructionswill be executed if and only if the corresponding option is on. The obvious use is for instructions that should be part of the system but executed only in some circumstances, for example to provide extra debugging information.

The final instruction is connected with Design by Contract&#153;. The instruction check Assertion end , where Assertion is a sequence of zero or more assertions, will have no effect unless assertion monitoring is turned on at the Check level or higher. If so it will evaluate all the assertions listed, having no further effect if they are all satisfied; if any one of them does not hold, the instruction will trigger an exception.

This instruction serves to state properties that are expected to be satisfied at some stages of the computation -- other than the specific stages, such as routine entry and exit, already covered by the other assertion mechanisms such as preconditions, postconditions and invariants. A recommended use of check involves calling a routine with a precondition, where the call, for good reason, does not explicitly test for the precondition. Consider a routine of the form

    r (ref: SOME_REFERENCE_TYPE) is
    	require
    		not_void: ref /= Void
    	do
    		ref.some_feature
    		...
    	end

Because of the call to some_feature , the routine will only work if its precondition is satisfied on entry. To guarantee this precondition, the caller may protect it by the corresponding test, as in

    if x /= Void then a.r (x) end

but this is not the only possible scheme; for example if an create x appears shortly before the call we know x is not void and do not need the protection. It is a good idea in such cases to use a check instruction to document this property, if only to make sure that a reader of the code will realize that the omission of an explicit test (justified or not) was not a mistake. This is particularly appropriate if the justification for not testing the precondition is less obvious. For example x could have been obtained, somewhere else in the algorithm, as clone (y) for some y that you know is not void. You should document this knowledge by writing the call as

    check
    	x_not_void: x /= Void end
    		-- Because x was obtained as a clone of y,
    		-- and y is not void because [etc.]
    end
    a.r (x)

Note the recommended convention: extra indentation of the check part to separate it from the algorithm proper; and inclusion of a comment listing the rationale behind the developer's decision not to check explicitly for the precondition.

In production mode with assertion monitoring turned off, this instruction will have no effect. But it will be precious for a maintainer of the software who is trying to figure out what it does, and in the process to reconstruct the original developer's reasoning. (The maintainer might of course be the same person as the developer, six months later.) And if the rationale is wrong somewhere, turning assertion checking on will immediately uncover the bug.

## Obsolete features and classes

One of the conditions for producing truly great reusable software is to recognize that although you should try to get everything right the first time around you won't always succeed. But if "good enough" may be good enough for application software, it's not good enough, in the long term, for reusable software. The aim is to get ever closer to the asymptote of perfection. If you find a better way, you must implement it. The activity of generalization, discussed as part of the lifecycle, doesn't stop at the first release of a reusable library.

This raises the issue of backward compatibility: how to move forward with a better design, without compromising existing applications that used the previous version?

The notion of obsolete class and feature helps address this issue. By declaring a feature as obsolete , using the syntax

    enter (i: INTEGER; x: G) is
    	obsolete
    		"Use ` put (x, i)' instead "
    	require
    		...
    	do
    		put (x, i)
    	end

you state that you are now advising against using it, and suggest a replacement through the message that follows the keyword obsolete , a mere string. The obsolete feature is still there, however; using it will cause no other harm than a warning message when someone compiles a system that includes a call to it. Indeed, you don't want to hold a gun to your client authors' forehead ("Upgrade now or die !"); but you do want to let them know that there is a new version and that they should upgrade at their leisure.

Besides routines, you may also mark classes as obsolete.

The example above is a historical one, involving an early change of interface for the EiffelBase library class ARRAY ; the change affected both the feature's name, with a new name ensuring better consistency with other classes, and the order of arguments, again for consistency. It shows the recommended style for using obsolete :

- In the message following the keyword, explain the recommended replacement. This message will be part of the warning produced by the compiler for a system that includes the obsolete element.
- In the body of the routine, it is usually appropriate, as here, to replace the original implementation by a call to the new version. This may imply a small performance overhead, but simplifies maintenance and avoids errors.

It is good discipline not to let obsolete elements linger around for too long. The next major new release, after a suitable grace period, should remove them.

The design flexibility afforded by the obsolete keyword is critical to ensure the harmonious long-term development of ambitious reusable software.

## Creation variants

The basic forms of creation instruction, and the one most commonly used, are the two illustrated earlier ("Creating and initializing objects", page 20):

    create x.make (2000)
    create x

the first one if the corresponding class has a create clause, the second one if not. In either form you may include a type name in braces, as in

    create {SAVINGS_ACCOUNT} x.make (2000)

which is valid only if the type listed, here SAVINGS_ACCOUNT , conforms to the type of x , assumed here to be ACCOUNT . This avoids introducing a local entity, as in

    local
    	xs: SAVINGS_ACCOUNT
    do
    	create xs.make (2000)
    	x := xs
    	...

and has exactly the same effect. Another variant is the creation expression, which always lists the type, but returns a value instead of being an instruction. It is useful in the following context:

    some_routine (create {ACCOUNT}.make (2000))

which you may again view as an abbreviation for a more verbose form that would need a local entity, using a creation instruction:

    local
     	x: ACCOUNT
    do
    	create x.make (2000)
    	some_routine (x)
    	...

Unlike creation instructions, creation expressions must always list the type explicitly, {ACCOUNT} in the example. They are useful in the case shown: creating an object that only serves as an argument to be passed to a routine. If you need to retain access to the object through an entity, the instruction create x ... is the appropriate construct.

The creation mechanism gets an extra degree of flexibility through the notion of default_create . The simplest form of creation instruction, create x without an explicit creation procedure, is actually an abbreviation for create x.default_create , where default_create is a procedure defined in class ANY to do nothing. By redefining default_create in one of your classes, you can ensure that create x will take care of non-default initialization (and ensure the invariant if needed). When a class has no create clause, it's considered to have one that lists only default_create . If you want to allow create x as well as the use of some explicit creation procedures, simply list default_create along with these procedures in the create clause. To disallow creation altogether, include an empty create clause, although this technique is seldom needed since most non-creatable classes are deferred, and one can't instantiate a deferred class.

One final twist is the mechanism for creating instances of formal generic parameters. For x of type G in a class C [G] , it wouldn't be safe to allow create x , since G stands for many possible types, all of which may have their own creation procedures. To allow such creation instructions, we rely on constrained genericity. You may declare a class as

    [G -> T create cp end]

to make G constrained by T , as we learned before, and specify that any actual generic parameter must have cp among its creation procedures. Then it's permitted to use create x.cp , with arguments if required by cp , since it is guaranteed to be safe. The mechanism is very general since you may use ANY for T and default_create for cp . The only requirement on cp is that it must be a procedure of T , not necessarily a creation procedure; this permits using the mechanism even if T is deferred, a common occurrence. It's only descendants of T that must make cp a creation procedure, by listing it in the create clause, if they want to serve as actual generic parameters for C .

## Tuple types

The study of genericity described arrays. Another common kind of container objects bears some resemblance to arrays: sequences, or "tuples", of elements of specified types. The difference is that all elements of an array were of the same type, or a conforming one, whereas for tuples you will specify the types we want for each relevant element. A typical tuple type is of the form

    TUPLE [X, Y, Z]

denoting a tuple of least three elements, such that the type of the first conforms to X , the second to Y , and the third to Z .

You may list any number of types in brackets, including none at all: TUPLE , with no types in brackets, denotes tuples of arbitrary length.

The syntax, with brackets, is intentionally reminiscent of generic classes, but TUPLE is a reserved word, not the name of a class; making it a class would not work since a generic class has a fixed number of generic parameters. You may indeed use TUPLE to obtain the effect of a generic class with a variable number of parameters.

To write the tuples themselves -- the sequences of elements, instances of a tuple type -- you will also use square brackets; for example

    [x1, y1, z1]

with x1 of type X and so on is a tuple of type TUPLE [X, Y, Z] .

The definition of tuple types states that TUPLE [X1 ... Xn] denotes sequences of at least n elements, of which the first n have types respectively conforming to X1, ..., Xn . Such a sequence may have more than n elements.

Features available on tuple types include count: INTEGER , yielding the number of elements in a tuple, item (i: INTEGER): ANY which returns the i -th element, and put which replaces an element.

Tuples are appropriate when these are the only operations you need, that is to say, you are using sequences with no further structure or properties. Tuples give you "anonymous classes" with predefined features count , item and put . A typical example is a general-purpose output procedure that takes an arbitrary sequence of values, of arbitrary types, and prints them. It may simply take an argument of type TUPLE , so that clients can call it under the form

    write ([ your_integer , your_real, your_account])

As soon as you need a type with more specific features, you should define a class.