3.3.5.1   Request Methods

For an instance to be able to send an answer to a request triggered by a caller, of course that instance needs to know the caller PID.

Therefore requests have to specify, as the third element of the call tuple, an additional information: the PID to which the answer should be sent, which is almost always the caller (hence the self() in the actual calls).

So these three potential information (request name, parameters, reference of the sender, i.e. an atom, usually a list, and a PID) are gathered in a tuple sent as a message: {request_name,[Arg1,Arg2,..],self()}.

If only one parameter is to be sent, and if that parameter is not a list, then this can become {request_name,Arg,self()}.

For example: MyCat ! {getAge,[],self()} or MyCalculator ! {sum,[1,2,4],self()}.

receive should then be used by the caller to retrieve the request result, like in:

MyPoint ! {getCoordinates,[],self()},
receive
                 {wooper_result,[X,Y]} ->
                                 [...];
                 % Could be left out to ignore errors.
                 % Otherwise one might prefer making this caller block:
                 Error ->
                                 [...]
end,

3.3.5.2   Oneway Methods

When calling oneway methods, the caller does not have to specify its PID, as no result is expected to be returned back to it.

If ever the caller sends by mistake its PID nevertheless, a warning would be sent back to it, the atom wooper_method_returns_void instead of {wooper_result,Result}.

The proper way of calling a oneway method is to send to it an Erlang message that is:

• either a pair, i.e. a 2-element tuple (therefore with no PID specified): {oneway_name,[Arg1,Arg2,..]} or {oneway_name,Arg} if Arg is not a list. For example: MyPoint ! {setCoordinates,[14,6]} or MyCat ! {setAge,5}
• or, if the oneway do not take any parameter, just the atom oneway_name. For example: MyCat ! declareBirthday

No return should be expected (the called instance does not even know the PID of the caller), so no receive should be attempted on the caller side.

Due to the nature of oneways, if an error occurs instance-side during the call, the caller will never be notified of it.

However, to help the debugging, an error message is then logged (using error_logger:error_msg) and the actual error message, the one that would be sent back to the caller if the method was a request, is given to erlang:exit instead.

3.3.6.1   Execution Success: {wooper_result,ActualResult}

If the execution of a method succeeded, and if it is a request (not a oneway, which would not return anything), then {wooper_result,ActualResult} will be sent back.

Otherwise one of the following error messages will be emitted.

3.3.6.2   Execution Failures

When the execution of a method fails, three main error results can be returned.

A summary could be:

MyPoint ! {getCoordinates,[],self()},
receive
    {wooper_result, [X,Y] } ->
                 [...];
    {wooper_method_not_found, Pid, Class, Method, Arity, Params} ->
                 [...];
    {wooper_method_failed, Pid, Class, Method, Arity, Params, ErrorTerm} ->
                 [...];
    % Error term can be a tuple {Pid,Error} as well, depending on the exit:
    {wooper_method_failed, Pid, Class, Method, Arity, Params, {Pid,Error}} ->
                 [...];
    {wooper_method_faulty_return, Pid, Class, Method, Arity, Params, UnexpectedTerm} ->
                 [...];
    wooper_method_returns_void ->
                 [...];
    OtherError ->
                 % Should never happen:
                 [...]
end.

MyPoint ! {getCoordinates,[],self()},
receive
    {wooper_result, [X,Y] } ->
                 [...]
end.

3.3.7.1   For Requests

Requests will use ?wooper_return_state_result(NewState,Result): the new state will be kept by the instance, whereas the result will be sent to the caller. Hence wooper_return_state_result means that the method returns a state and a result.

For example:

getAge(State) ->
                 ?wooper_return_state_result(State,?getAttr(age)).

All methods are of course given the parameters specified at their call.

For example, we can declare:

giveBirth(State,NumberOfMaleChildren,NumberOfFemaleChildren) ->
                 [..]

And then we may call it, in the case of a cat having 2 male kitten and 3 female ones, with:

MyCat ! {giveBirth,[2,3],self()}.

Requests can access to one more information than oneways: the PID of the caller that sent the request.

This can be done by using the getSender macro, which is automatically set by WOOPER:

giveBirth(State,NumberOfMaleChildren,NumberOfFemaleChildren) ->
  CallerPID = ?getSender(),
  [..]

Thus requests have access to their caller PID without having to specify it twice, i.e. with no need to specify it in the parameters as well as in the third element of the call tuple: instead of MyCat ! {giveBirth,[2,3,self()],self()}., only MyCat ! {giveBirth,[2,3],self()}. can be used, while still letting the possibility for the called request (here giveBirth/3, for a state and two parameters) to access the caller PID thanks to the getSender macro, and maybe store it for a later use.

Note that having to handle explicitly the caller PID is rather uncommon, as WOOPER takes care automatically of the sending of the result back to the caller.

The getSender macro should only be used for requests, as of course the sender PID has no meaning in the case of oneways.

If that macro is called nevertheless from a oneway, then it returns the atom undefined.

3.3.7.2   For Oneways

Oneway will use ?wooper_return_state_only(NewState): the instance state will be updated, but no result will be returned to the caller, which is not even known.

For example:

setAge(State,NewAge) ->
  ?wooper_return_state_only( ?setAttribute(State,age,NewAge) ).

can be called that way:

MyCat ! {setAge,4}.
% No result to expect.

Oneways may leave the state unchanged, only being called for side-effects, for example:

displayAge(State) ->
  io:format("My age is ~B~n.",[ ?getAttr(age) ]),
  ?wooper_return_state_only(State).

3.3.7.3   Usefulness Of These Two Return Macros

The two macros are actually quite simple, they are just here to structure the method implementations (helping the method developer not mixing updated states and results), and to help ensuring, in debug mode, that methods return well-formed results: an atom is then prepended to the returned tuple and WOOPER matches it during post-invocation, before handling the return, for an increased safety.

For example, in debug mode, ?wooper_return_state_result(AState,AResult) will simply translate into {wooper_result,AState,AResult}, and when the execution of the method is over, WOOPER will attempt to match the method returned value with that triplet (3-tuple).

Similarly, ?wooper_return_state_only(AState) will translate into {wooper_result,AState}.

If not in debug mode, then the wooper_result element will not be used in the returned tuples, for example ?wooper_return_state_result(AState,AResult) will just be {AState,AResult}.

Performances should increase a bit, at the expense of a less safe checking of the values returned by methods.

The two wooper_return_state_* macros have been introduced so that the unwary developer does not forget that his requests should not only return a result, by also a state, and that the order is always: first the state, then the result, not the other way round.

3.4.1.1   The setAttribute/3 Macro

Setting an attribute (creating and/or modifying it) should be done with the setAttribute macro: ?setAttribute(AState,AttributeName,NewAttributeValue).

For example, AgeState = ?setAttribute(State,age,3) will return a new state, bound to AgeState, exact copy of State (with all the attribute pairs equal) but for the age attribute, whose value will be set to 3 (whether or not this attribute was already defined in State).

Therefore during the method execution multiple states can be defined (ex: State and AgeState), before all but the one that is returned are garbage-collected.

Note that the corresponding state duplication remains efficient both in terms of processing and memory, as the different underlying hashtables (ex: State and AgeState) actually share all their terms except the one modified, thanks to the immutability of Erlang variables, which allows to reference rather than copy.

In various cases, notably in constructors, one needs to define a series of attributes in a row, but chaining setAttribute calls with intermediate states is not really convenient.

A better solution is to use the setAttributes macro (note the plural) to set a list of attribute name/attribute value pairs.

For example, ConstructedState = ?setAttributes(State,[ {age,3}, {whisker_color,white} ]) will return a new state, exact copy of State but for the listed attributes, set to their respective specified value.

3.4.1.2   The removeAttribute/2 Macro

An attribute may also be removed, using the removeAttribute macro.

For example: NewState = ?removeAttribute(State,an_attribute). The resulting state will have no key corresponding to an_attribute.

Neither setAttribute nor removeAttribute can fail, regardless of the attribute being already existing or not.

3.4.2.1   The hasAttribute/2 Macro

To test whether an attribute is defined, use the hasAttribute macro: ?hasAttribute(AState,AttributeName), which returns either true or false, and cannot fail.

For example, true = ?hasAttribute(State,whisker_color) matches if and only if the attribute whisker_color is defined in state State.

Note that generally it is a bad practice to define attributes outside of the constructor of an instance, as the availability of an attribute could then depend on the actual state, which is an eventuality generally difficult to manage reliably.

A better approach is instead to define all possible attributes directly from the constructor. They would then be assigned to their initial value and, if none is appropriate, they should be set to the atom undefined (instead of not being defined at all).

3.4.2.2   The getAttribute/2 Macro

Getting the value of an attribute should be done with the getAttribute macro: ?getAttribute(AState,AttributeName).

For example, MyColor = ?getAttribute(State,whisker_color) returns the value of the attribute whisker_color from state State.

The requested attribute may not exist in the specified state. In this case, a bad match is triggered.

In the previous example, if the attribute whisker_color had not been defined, then getAttribute would have returned: {{badmatch,{hashtable_key_not_found,whisker_color}},[{hashtable,getEntry,2},...

3.4.2.3   The getAttr/2 Macro

Quite often, when having to retrieve the value of an attribute from a state variable, that variable will be named State, notably when using directly the original state specified in the method declaration.

In this case, the getAttr macro can be used: ?getAttr(whisker_color) expands as ?getAttribute(State,whisker_color), and is a bit shorter.

3.4.3.1   The addToAttribute/3 Macro

The corresponding signature is addToAttribute(State,AttributeName,Value): when having a numerical attribute, adds specified number to the attribute.

For example: NewState = ?addToAttribute(State,a_numerical_attribute,6).

If the target attribute does not exist, will trigger {{badmatch,undefined},[{hashtable,addToEntry,3},...

If it exists but no addition can be performed on it (meaningless for the type of the current value), will trigger {badarith,[{hashtable,addToEntry,3},...

3.4.3.2   The substractFromAttribute/3 Macro

The corresponding signature is substractFromAttribute(State,AttributeName,Value): when having a numerical attribute, subtracts specified number from the attribute.

For example: NewState = ?substractFromAttribute(State,a_numerical_attribute,1).

If the target attribute does not exist, will trigger {{badmatch,undefined},[{hashtable,substractFromEntry,3},...

If it exists but no subtraction can be performed on it (meaningless for the type of the current value), will trigger {badarith,[{hashtable,substractFromEntry,3},...

3.4.3.3   The toggleAttribute/2 Macro

The corresponding signature is toggleAttribute(State,BooleanAttributeName): when having a boolean attribute, whose values are either true or false, sets the opposite logical value to the current one.

For example: NewState = ?toggleAttribute(State,a_boolean_attribute).

If the target attribute does not exist, will trigger {{case_clause,undefined},[{hashtable,toggleEntry,2},...

If it exists but is neither true or false, will trigger {{case_clause,{value,..}},[{hashtable,toggleEntry,2},...

3.4.3.4   The appendToAttribute/3 Macro

The corresponding signature is appendToAttribute(State,AttributeName,Element): when having a list attribute, appends specified element to the attribute list, in first position.

For example, if a_list_attribute was already set to [see_you,goodbye] in State, then after NewState = ?appendToAttribute(State,a_list_attribute,hello), the a_list_attribute attribute defined in NewState will be equal to [hello,see_you,goodbye].

If the target attribute does not exist, will trigger {{badmatch,undefined},[{hashtable,appendToEntry,3},...

If it exists but is not already a list, it will not crash but will create an ill-formed list (ex: [8|false] when appending 8 to false, which is not a list).

3.4.3.5   The deleteFromAttribute/3 Macro

The corresponding signature is deleteFromAttribute(State,AttributeName,Element): when having a list attribute, deletes first match of specified element from the attribute list.

For example: NewState = ?deleteFromAttribute(State,a_list_attribute,hello), with the value corresponding to the a_list_attribute attribute in State variable being [goodbye,hello,cheers,hello,see_you] should return a state whose a_list_attribute attribute would be equal to [goodbye,cheers,hello,see_you], all other attributes being unchanged.

If the target attribute does not exist, will trigger {{badmatch,undefined},[{hashtable,deleteFromEntry,3},...

If it exists but is not already a list, it will trigger {function_clause,[{lists,delete,[..,..]},{hashtable,deleteFromEntry,3}.

If no element in the list matches the specified one, no error will be triggered and the list will be kept as is.

3.4.3.6   The popFromAttribute/2 Macro

The corresponding signature is popFromAttribute(State,AttributeName): when having an attribute of type list, this macro removes the head from the list and returns a pair made of the updated state (same state except that the corresponding list attribute has lost its head, it is equal to the list tail now) and of that head.

For example: {NewState,Head} = ?popFromAttribute(State,a_list_attribute). If the value of the attribute a_list_attribute was [5,8,3], its new value (in NewState) will be [8,3] and Head will be bound to 5.

3.4.3.7   The addKeyValueToAttribute/4 Macro

The corresponding signature is addKeyValueToAttribute(State,AttributeName,Key,Value): when having an attribute whose value is a hashtable (therefore, it is a hashtable in the WOOPER hashtable), adds specified key/value pair to that hashtable attribute.

For example: WithTableState = ?setAttribute( State, my_hashtable, hashtable:new() ), NewState = ?addKeyValueToAttribute( WithTableState, my_hashtable, my_key, my_value ) will result in having the attribute my_hashtable in state variable WithTableState being an hashtable with only one entry, whose key is my_key and whose value is my_value.

See wooper.hrl for the actual definition of most of these WOOPER constructs.

3.6.1.1   Role of a new/construct Pair

Whereas the purpose of new/new_link is to create a working instance on the user's behalf, the role of construct is to initialise an instance of that class while being able to be chained for inheritance, as explained later.

All calls to a new operator result in an underlying call to the corresponding construct method.

For example, MyCat = class_Cat:new(A,B,C,D) will rely on class_Cat:construct/5 to set-up a proper initial state for the MyCat instance: class_Cat:construct(State,A,B,C,D) will be called for

The new_link operator behaves exactly as the new operator, except that it creates an instance that is Erlang-linked with the process that called that operator, exactly like spawn_link behaves compared to spawn.

The new and new_link operators are automatically defined by WOOPER, but they rely on the class-specific user-defined construct special method (only WOOPER is expected to call this method). This construct method is the one that must be implemented by the class developer.

Only one version of new, new_link and construct can be defined, but they may branch to as many subconstructors as needed.

For example:

MyFirstDog  = Class_Dog:new( create_from_colors, [sand,white] ),
MySecondDog = Class_Dog:new( create_from_age, 5 ),
MyThirdDog  = Class_Dog:new( create_from_weight, 4.4 ).

3.6.1.2   The Various Ways of Creating An Instance

As shown with the new_link operator, even with the same set of constructing parameters, many variations of new can be imagined: linked or not, synchronous or not, with a time-out or not, on current node or on a user-specified one, etc.

For a class whose construction needs N actual parameters, the following construction operators are built-in:

• instance is to be created on the local node:
  • non-blocking: new/N and new_link/N
  • blocking: synchronous_new/N and synchronous_new_link/N
  • blocking with time-out: synchronous_timed_new/N and synchronous_timed_new_link/N
• instance is to be created on specified remote node:
  • non-blocking: remote_new/N+1 and remote_new_link/N+1
  • blocking: remote_synchronous_new/N+1 and remote_synchronous_new_link/N+1
  • blocking with time-out: remote_synchronous_timed_new/N+1 and remote_synchronous_timed_new_link/N+1

The supported new variations are detailed below.

3.6.1.3   Declaration of the new/construct Pair

When an instance is created, user-specified parameters are given to the relevant new operator, notably to set up the instance initial state, i.e. its attributes. These parameters must be declared thanks to the wooper_construct_parameters define.

For example, -define( wooper_construct_parameters, Age, Gender ). implies that two parameters, an age and a gender, are needed for an instance to be created.

If the instance is created without needing any parameter, then no wooper_construct_parameters macro should be defined at all (i.e. using -define( wooper_construct_parameters,). is not allowed).

In the general case where there is at least one parameter, the WOOPER-defined new operators automatically transmit these parameters to the construct method.

Based on the wooper_construct_parameters define (let us suppose N constructor parameters are listed in it), all the variations of the new operator and construct can be declared thanks to:

% Declaring all variations of WOOPER standard life-cycle operations:
% (template pasted, two replacements performed to update arities)
-define( wooper_construct_export, new/N, new_link/N,
    synchronous_new/N, synchronous_new_link/N,
    synchronous_timed_new/N, synchronous_timed_new_link/N,
    remote_new/N+1, remote_new_link/N+1, remote_synchronous_new/N+1,
    remote_synchronous_new_link/N+1, remote_synchronous_timed_new/N+1,
    remote_synchronous_timed_new_link/N+1, construct/N+1 ).

As there are quite a lot of construction operators available, the recommended mode of operation of declaring them all is to use the following template:

% Declaring all variations of WOOPER standard life-cycle operations:
% (template pasted, two replacements performed to update arities)
-define( wooper_construct_export, new/A, new_link/A,
    synchronous_new/A, synchronous_new_link/A,
    synchronous_timed_new/A, synchronous_timed_new_link/A,
    remote_new/B, remote_new_link/B, remote_synchronous_new/B,
    remote_synchronous_new_link/B, remote_synchronous_timed_new/B,
    remote_synchronous_timed_new_link/B, construct/B, delete/1 ).

and to use your text editor to replace A with your actual N and B with N+1.

If the class does not declare a specific destructor, then the corresponding declaration in the previous template (delete/1) must be removed.

For example, if wanting to create a bird (MyBird = class_Bird:new(Age,Gender)), we would have N=2 (two actual constructing parameters: age and gender), thus A has to be replaced by 2, and B by 3:

We see that construct needs N+1 parameters instead of N, to account for its first additional parameter, which is the State variable.

3.6.1.4   Some Examples

They can be used as templates:

-module(class_Bird).
-define( wooper_superclasses, [class_X,class_Y] ).
-define( wooper_construct_parameters, Age, Gender ).

% Declaring all variations of WOOPER standard life-cycle operations:
% (template pasted, two replacements performed to update arities)
-define( wooper_construct_export, new/2, new_link/2,
    synchronous_new/2, synchronous_new_link/2,
    synchronous_timed_new/2, synchronous_timed_new_link/2,
    remote_new/3, remote_new_link/3, remote_synchronous_new/3,
    remote_synchronous_new_link/3, remote_synchronous_timed_new/3,
    remote_synchronous_timed_new_link/3, construct/3, delete/1 ).

% Method declarations.
-define( wooper_method_export, my_first_method/X, second_method/Y ).

% Allows to define WOOPER base variables and methods for that class:
-include("wooper.hrl").

% Using the construct macro is prefered to duplicating the list of
% parameters:
construct( State, ?wooper_construct_parameters ) ->
  ...

If no construction-related parameter was needed, then it would become:

-module(class_OtherBird).
-define( wooper_superclasses, [class_X,class_Y] ).
% No '-define( wooper_construct_parameters,).' here!

% Declaring all variations of WOOPER standard life-cycle operations:
% (template pasted, two replacements performed to update arities)
-define( wooper_construct_export, new/0, new_link/0,
    synchronous_new/0, synchronous_new_link/0,
    synchronous_timed_new/0, synchronous_timed_new_link/0,
    remote_new/1, remote_new_link/1, remote_synchronous_new/1,
    remote_synchronous_new_link/1, remote_synchronous_timed_new/1,
    remote_synchronous_timed_new_link/1, construct/1, delete/1 ).

% Method declarations.
-define( wooper_method_export, my_first_method/X, second_method/Y ).

% Allows to define WOOPER base variables and methods for that class:
-include("wooper.hrl").

construct( State ) ->
  ...

All variations of the new operator are always defined automatically by WOOPER: nothing special is to be done for them, besides the wooper_construct_export declaration we just mentioned here.

3.6.1.5   Definition of the construct Method

In the context of class inheritance, the construct methods are expected to be chained: they must be designed to be called by the ones of their child classes, and they must call themselves the constructors of their mother classes, if any.

Hence they always take the current state of the instance being created as a starting base, and returns it once updated, first from the direct mother classes, then by this class itself.

For example, class_Cat inherits directly from class_Mammal and from class_ViviparousBeing, and has only one attribute (whisker_color) on its own:

[..]
-define(wooper_superclasses,[class_Mammal,class_ViviparousBeing]).
[..]
-define(wooper_construct_parameters,Age,Gender,FurColor,WhiskerColor).
[..]
-define( wooper_construct_export, new/4, new_link/4,
    synchronous_new/4, synchronous_new_link/4,
    synchronous_timed_new/4, synchronous_timed_new_link/4,
    remote_new/5, remote_new_link/5, remote_synchronous_new/5,
    remote_synchronous_new_link/5, remote_synchronous_timed_new/5,
    remote_synchronous_timed_new_link/5, construct/5 ).

[..]
% Constructs a new Cat.
construct(State,?wooper_construct_parameters) ->
    % First the direct mother classes:
    MammalState = class_Mammal:construct( State, Age, Gender, FurColor ),
    ViviparousMammalState = class_ViviparousBeing:construct( MammalState ),
    % Then the class-specific attributes:
    ?setAttribute( ViviparousMammalState, whisker_color, WhiskerColor ).

The fact that the Mammal class itself inherits from the Creature class must not appear here: it is to be managed directly by class_Mammal:construct (at any given inheritance level, only direct classes must be taken into account).

One should ensure that, in constructors, the successive states are always built from the last updated one, unlike:

% WRONG, the age update is lost:
construct(State,Age,Gender) ->
    AgeState = setAttribute(State,age,Age),
                 % AgeState should be used here, not State:
    setAttribute(State,gender,Gender),

This would be correct:

% RIGHT but a bit clumsy:
construct(State,Age,Gender) ->
    AgeState = setAttribute(State,age,Age),
    setAttribute(AgeState,gender,Gender).

Recommended form:

% BEST:
construct(State,Age,Gender) ->
    setAttributes( State, [ {age,Age}, {gender,Gender} ]).

3.6.2.1   Automatic Chaining Of Destructors

We saw that, when implementing a constructor (construct/N), like in all other OOP approaches the constructors of the direct mother classes have to be explicitly called, so that they can be given the proper parameters.

Conversely, with WOOPER, when defining a destructor for a class (delete/1), one only has to specify what are the specific operations (if any) that are required so that an instance of that class is deleted: the proper calling of the destructors of mother classes across the inheritance graph is automatically taken in charge by WOOPER.

Note also that as soon as you define a destructor, you have to declare it in the wooper_construct_export section.

For example:

-define( wooper_construct_export, new/N, [..], construct/N+1, delete/1 ).

Otherwise a warning will be issued (delete/1 is unused), and the overridden destructor would not be called then.

3.6.2.2   Asynchronous Destructor: delete/1

More precisely, either the class implementer does not define at all a delete/1 operator, or it defines it without needing to call the ones of the mother class(es), like in:

delete(State) ->
  io:format("An instance of class ~w is being deleted now!", [?MODULE] ).

In both cases, when the instance will be deleted (i.e. MyInstance ! delete is issued), WOOPER will take care of:

• calling any destructor defined for that class
• then calling the ones of the direct mother classes, which will in turn call the ones of their mother classes, and so on

Note that the destructors for direct mother classes will be called in the reverse order of the one according to the constructors ought to have been called: if a class class_X declares class_A and class_B as mother classes (in that order), then in the class_X:construct definition the implementer is expected to call class_A:construct and then class_B:construct, whereas on deletion the WOOPER-enforced order of execution will be: class_X:delete, then class_B:delete, then class_A:delete, for the sake of symmetry.

3.6.2.3   Synchronous Destructor: synchronous_delete/1

Finally, the delete/1 operator does not need to be exported, since it will be triggered only thanks to messages.