Motivations & Purpose

Some problems may almost only be tackled efficiently thanks to an object-oriented modelling.

The set of code and conventions proposed here allows to benefit from all the main OOP features (including polymorphism, life cycle management, state management, passive or active instances, and multiple inheritance) directly from Erlang (which natively does not rely on the OOP paradigm), so that - in the cases where it makes sense - an object-oriented approach at the implementation level can be easily achieved.

The WOOPER Mode of Operation in a Nutshell

The WOOPER OOP concepts translate into Erlang constructs according to the following mapping:

In practice, developing a class with WOOPER mostly involves including the wooper.hrl header file and respecting the WOOPER conventions detailed below.

Example

Here is a simple example of how a WOOPER class can be defined and used.

It shows new/delete operators, method calling (both request and oneway), and inheritance.

A cat is here a viviparous mammal, as defined below (this is a variation of our more complete class_Cat.erl example):

-module(class_Cat).

% Optional:
-define(class_description,"Models a domestic cat").

% Determines what are the direct mother classes of this class (if any):
-define(superclasses,[class_Mammal,class_ViviparousBeing]).

% Declaration of class-specific attributes:
% (optional, yet recommended for clarity)
-define(class_attributes,[
          {meow_style,style(),const,"the kind of meow to expect"},
          {whisker_color,"the color of this cat's whiskers"}]).

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

% No need to export constructors, destructor or methods.
% Type specifications remain optional (yet are recommended).

% Constructs a new Cat.
construct(State,Age,Gender,FurColor,WhiskerColor) ->
   % First the direct mother classes:
   MammalState = class_Mammal:construct(State,Age,Gender,FurColor),
   ViviparousMammalState = class_ViviparousBeing:construct(MammalState),
   % Then the class-specific attributes; returns an updated state:
   setAttribute(ViviparousMammalState,whisker_color,WhiskerColor).

destruct(State) ->
   io:format( "Deleting cat ~w! (overridden destructor)~n", [self()] ),
   State.

% Member methods.

% A cat-specific request, supposing the developer missed the fact
% that it is a const one (no problem):
getWhiskerColor(State)->
   wooper:return_state_result(State,?getAttr(whisker_color)).

% A (non-const) oneway, with a spec:
-spec setWhiskerColor(wooper:state(),foo:color()) -> oneway_return().
setWhiskerColor(State,NewColor)->
   NewState = setAttribute( State, whisker_color, NewColor ),
   wooper:return_state(NewState).

% Overrides any request method defined in the Mammal class:
% (const request)
canEat(State,soup) ->
   wooper:const_return_result(true);

canEat(State,croquette) ->
   wooper:const_return_result(true);

canEat(State,meat) ->
   wooper:const_return_result(true);

canEat(State,_OtherFood) ->
   wooper:const_return_result(false).

% Static method:
get_default_whisker_color() ->
   wooper:return_static(white).

Straightforward, isn't it? We will discuss it in-depth, though.

To test this class (provided that GNU make and the latest stable version of Erlang are available in one's environment, see Prerequisites for more information), one can easily install Ceylan-WOOPER, which depends on Ceylan-Myriad, hence is to be installed first:

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Myriad.git myriad
$ cd myriad && make all && cd ..

$ git clone https://github.com/Olivier-Boudeville/Ceylan-WOOPER.git wooper
$ cd wooper && make all

(for OTP compliance, using short names, such as myriad or wooper, for clones rather than long ones, such as Ceylan-Myriad or Ceylan-WOOPER, is recommended)

Running the cat-related example just then boils down to:

$ cd examples && make class_Cat_run

In the examples directory, the test defined in class_Cat_test.erl should run against the class defined in class_Cat.erl, and no error should be detected:

Running unitary test class_Cat_run (second form)

--> Testing module class_Cat_test.
[..]
Deleting cat <0.80.0>! (overridden destructor)
Deleting mammal <0.80.0>! (overridden destructor)
Actual class from destructor: class_Cat.
Deleting mammal <0.82.0>! (overridden destructor)
This cat could be created and be synchronously deleted, as expected.
--> Successful end of test.
(test finished, interpreter halted)

That's it!

Now, more in-depth explanations.

Classes

-define(class_description,"Class in charge of implementing the "
                            "Foobar service.").

-define(superclasses,[]).

-define(superclasses,[class_Mammal,class_ViviparousBeing]).

> class_Cat:get_superclasses().
[class_Mammal,class_ViviparousBeing]

Instances

Methods

They can be either:

• member methods: they applies to a specific instance (of a given class), like in: MyCatPid ! declareBirthday
• or static methods: they are general to a class, not targeting specifically an instance of it, like in: class_Cat:get_default_mew_duration()

Unless specified otherwise, just mentioning method by itself refers to a member method. Static methods are discussed in their specific subsection (see Static Methods).

Member methods can be publicly called by any process (be it WOOPER-based or not) - provided of course it knows the PID of that instance - whether locally or remotely (i.e. on other networked computers, like with RMI or with CORBA, or directly from the same Erlang node), distribution (and parallelism) being seamlessly managed thanks to Erlang.

Member methods (either inherited or defined directly in the class) are mapped to specific Erlang functions that are triggered by Erlang messages.

For example, our cat class may define, among others, following member methods (actual arities to be discussed later):

• canEat, taking one parameter specifying the type of food, and returning whether the corresponding cat can eat that kind of food; here the implementation should be cat-specific (i.e. specific to cats and also, possibly, specific to this very single cat), whereas the method signature shall be shared by all beings
• getWhiskersColor, taking no parameter, returning the color of its whiskers; this is indeed a purely cat-specific method, and different cats may have different whisker colors; as this method, like the previous one, returns a result to the caller, it is a request method
• declareBirthday, incrementing the age of our cat, not taking any parameter nor returning anything; it will be therefore be implemented as a oneway method (i.e. not returning any result to the caller, hence not even needing to know it), whose call is only interesting for its effect on the state of this cat: here, making it one year older
• setWhiskerColor, assigning the specified color to the whiskers of that cat instance, not returning anything (another oneway method, then)

Declaring a birthday is not cat-specific, nor mammal-specific: we can consider it being creature-specific. Cat instances should then inherit this method, preferably indirectly from the class_Creature class, in all cases without having to specify anything, since the superclasses define already implies it (implying one time for all that cats are creatures and thus, unless specified otherwise, are and behave as such). Of course this inherited method may be overridden at will anywhere in the class hierarchy.

We will discuss the definition of these methods later, but for the moment let's determine their signatures and declarations, and how we are expected to call them.

% Calling the canEat request of our cat instance:
MyCat ! {canEat,soup,self()},
receive
    {wooper_result,true} ->
      io:format("This cat likes soup!!!");

    {wooper_result,false} ->
      io:format("This cat does not seem omnivorous.")
end,

% A parameter-less request:
MyCat ! {getWhiskersColor,[],self()},
receive
    {wooper_result,white} ->
      io:format("This cat has normal whiskers.");

    {wooper_result,blue} ->
      io:format("What a weird cat...")
end,

% A parameter-less oneway:
MyCat ! declareBirthday.

MyCat ! {getAge,[],self()}.

Douglas ! {askQuestionWithHint, [{meaning_of,"Life"},{maybe,42}], self()}.

MyCalculator ! {sum,[[1,2,4]],self()}.

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

{wooper_method_not_found,InstancePid,Classname,MethodName,
 MethodArity,ListOfActualParameters}

{wooper_method_not_found,InstancePid,Classname,MethodName,
 MethodArity,ListOfActualParameters}.

{wooper_method_not_found,<0.30.0>,class_Cat,layEggs,2,...}

{wooper_method_failed,InstancePid,Classname,MethodName,
 MethodArity, ListOfActualParameters,ErrorTerm}

{wooper_method_failed,<0.30.0>,class_Cat,myCrashingMethod,1,[],
 {{badmatch,create_bug},[..]]}

{wooper_method_faulty_return,InstancePid,Classname,MethodName,
 MethodArity,ListOfActualParameters,ActualReturn}``.

{wooper_method_faulty_return,<0.30.0>,class_Cat,
 myFaultyMethod,1,[],[{{state_holder,..]}

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 {Pid,Error} tuple 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,
[..]

declareSettings(State,Settings) ->
    NewState = register_settings(Settings,State),
    wooper:return_state_result(NewState,settings_declared).

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

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

getWhiskerColor(State) ->
   wooper:return_state_result(State,?getAttr(whisker_color)).

getWhiskerColor(State) ->
   wooper:const_return_result(?getAttr(whisker_color)).

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

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

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

-spec declareSettings(wooper:state(),settings()) ->
               request_return('settings_declared').
declareSettings(State,Settings) ->
    NewState = register_settings(Settings,State),
    wooper:return_state_result(NewState,settings_declared).

-spec getWhiskerColor(wooper:state()) ->
               const_request_return(color()).
getWhiskerColor(State) ->
   wooper:const_return_result(?getAttr(whisker_color)).

setAge(State,NewAge) ->
    wooper:return_state(setAttribute(State,age,NewAge)).

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

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

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

-spec setAge(wooper:state,age()) -> oneway_return().
setAge(State,NewAge) ->
    wooper:return_state(setAttribute(State,age,NewAge)).

-spec displayAge(wooper:state) -> const_oneway_return().
displayAge(State) ->
    io:format("My age is ~B~n.",[?getAttr(age)]),
    wooper:const_return().

% Returns the name of this instance.
-spec getName(wooper:state()) -> request_return(name()).
getName(State) ->
  Name = nested_in_request(State),
  wooper:const_return_result(Name).

% (helper)
nested_in_request(State) ->
  ?getAttr(name).

% Returns the name of this instance.
-spec getName(wooper:state()) -> request_return(name()).
getName(State) ->
  nested_in_request(State).

% (helper)
nested_in_request(State) ->
  wooper:const_return_result(?getAttr(name)).

% (helper)
nested_in_request(State) ->
  ?getAttr(name).

{NewState,Result} = executeRequest(CurrentState,myRequestName,
                               ["hello",42])

{NewState,NewCounter} = executeRequest(CurrentState,
                               addToCurrentCounter,78)

{NewState,Sentence} = executeRequest(CurrentState,getLastSentence)

Color = executeConstRequest(CurrentState,getColor)

NewState = executeOneway(CurrentState,say,[ "hello", 42 ])

NewState = executeOneway(CurrentState,setAge,78)

NewState = executeOneway(CurrentState,declareBirthday)

executeConstOneway(CurrentState,displayAge)

AgeState = executeOnewayAs(State,class_Creature,setAge,NewAge)

Color = executeConstRequestAs(MyState,class_Vehicle,
                              getColorOf,[wheels])

get_default_whisker_color() ->
    wooper:return_static(black).

-spec determine_croquette_appeal(cat_name()) ->
           static_return('strong'|'moderate'|'weak').
determine_croquette_appeal(_CatName="Tortilla") ->
    wooper:return_static(strong);

determine_croquette_appeal(_CatName="Abysse") ->
    wooper:return_static(moderate).

PossibleColor = class_Cat:get_default_whisker_color(),
[..]

State Management

[{color,black}, {fur_color,sand}, {age,13}, {name,"Tortilla"}].

-define(class_attributes,[
            ATTR_DECL1,
            ATTR_DECL2,
            [...]
            ATTR_DECLN]).
[...]
-include("wooper.hrl").
[...]

{Name, Type, QualifierInfo, Description}

{age, integer(), {initial,18},
 "stores the current age of this creature"}

-define(class_attributes,[
    name,
    {age, integer(), "stores the current age of this creature"},
    birth_date,
    {weight, "total weight measured"}]).

NewState = setAttribute(AState, AttributeName, NewAttributeValue)

-spec setAttribute(wooper:state(), attribute_name(), attribute_value()) ->
                               wooper:state().

-spec setAttributes(wooper:state(), [{attribute_name(), attribute_value()}]) ->
                               wooper:state().

ConstructedState = setAttributes(MyState,
         [{age,3},{whisker_color,white}])

-spec swapInAttribute(wooper:state(), attribute_name(),
                      NewValue :: attribute_value()) ->
           {wooper:state(), PastValue:: attribute_value()}.

{NewState,PastColor} = swapInAttribute(AState,fur_color,_NewValue=black)

-spec removeAttribute(wooper:state(), attribute_name()) ->
                               wooper:state().

-spec hasAttribute(wooper:state(), attribute_name()) ->
                               boolean().

case hasAttribute(AState, fur_color) of

  true ->
    [...]

AttributeValue = getAttribute(AState, AttributeName)

-spec getAttribute(wooper:state(), attribute_name()) ->
                               attribute_value().

{key_not_found, whisker_color}

-spec getMaybeAttribute(wooper:state(), attribute_name()) ->
         maybe({'value', attribute_value()}).

case getMaybeAttribute(AState, AttributeName) of

   undefined ->
     [...];

   {value, AttrValue} ->
     [...]

end.

get_maybe_description(State) ->
  ?getMaybeAttr(my_description).

-spec addToAttribute(wooper:state(), attribute_name(), number()) ->
                               wooper:state().

MyState = addToAttribute(FirstState, a_numerical_attribute, 6)

-spec subtractFromAttribute(wooper:state(), attribute_name(), number()) ->
                               wooper:state().

MyState = subtractFromAttribute(FirstState, a_numerical_attribute, 7)

-spec toggleAttribute(wooper:state(), attribute_name()) ->
                               wooper:state().

NewState = toggleAttribute(State, my_boolean_attribute)

-spec appendToAttribute(wooper:state(), attribute_name(), term()) ->
                               wooper:state().

-spec deleteFromAttribute(wooper:state(), attribute_name(), term()) ->
                               wooper:state().

-spec popFromAttribute(wooper:state(), attribute_name()) ->
                               {wooper:state(), term()}.

-spec addKeyValueToAttribute(wooper:state(), attribute_name(),
                       table:key(), table:value()) -> wooper:state().

TableState = setAttribute(State, my_table, table:new()),
NewState = addKeyValueToAttribute(TableState, my_table, my_key, my_value)

Multiple Inheritance & Polymorphism

% Inherited methods work exactly the same as methods defined
% directly in the class:
MyCat ! {getAge,[],self()},
receive
  {wooper_result,Age} ->
    io:format( "This is a ~B year old cat.", [Age] )
end,

% Polymorphism is immediate:
% (class_Platypus inheriting too from class_Mammal,
% hence from class_Creature).
MyPetList = [MyCat,MyPlatypus],
[ begin
    PetPid ! {getAge,[],self()},
    receive
      {wooper_result,Age} ->
        io:format("This is a ~B year old creature.",[Age])
    end
  end || PetPid <- MyPetList ].

This is a 4 year old cat.
This is a 4 year old creature.
This is a 9 year old creature.

-define(superclasses,[class_X,class_Y,...]).

construct(State, DateOfBirth) ->
  case hasAttribute(State, birth_date) of

       % Already initialised, nothing more to do, shortcut:
       true ->
           State;

       % Full, actual initialisation, to happen exactly once per instance:
       false ->
           % Trigger side-effects, change state, etc.:
           InitState = init(State),
           % At least this attribute is defined:
           setAttribute(InitState, birth_date, DateOfBirth)

   end.

Life-Cycle

Basically, creation and destruction of instances are managed respectively thanks to the new/new_link and the delete operators (all these operators are WOOPER-reserved function names, for all arities, and are automatically generated), like in:

MyCat = class_Cat:new(Age,Gender,FurColor,WhiskerColor),
MyCat ! delete.

% If having defined class_Dog:construct/{1,3}:
MyFirstDog  = class_Dog:new(),
MySecondDog = class_Dog:new(_Weight=4.4,_Colors=[sand,white]).

MyCat = class_Cat:remote_new(TargetNode, Age, Gender,
                             FurColor, WhiskerColor).

% Local asynchronous creation:
MyFirstCat = class_Cat:new(_Age=1,male,brown,white),

% The same, but a crash of this cat will crash the current
% process too:
MySecondCat = class_Cat:new_link(2,female,black,white),

% This cat will be created on OtherNode, and the call will
% return only once it is up and running or once the creation
% failed. As moreover the cat instance is linked to the
% instance process, it may crash this calling process
% (unless it traps EXIT signals):
MyThirdCat = class_Cat:remote_synchronous_timed_new_link(
                               OtherNode,3,male,grey,black),
[...]

-spec construct(wooper:state(),P1,P2,..,PN) -> wooper:state().

-define(superclasses,[class_Mammal,class_ViviparousBeing]).

-define(class_attributes,[whisker_color]).

% Constructs a new Cat.
construct(State,Age,Gender,FurColor,WhiskerColor) ->
  % First the (chained) 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).

% 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),

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

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

-spec destruct(wooper:state()) -> wooper:state().

destruct(State) ->
    io:format("An instance of class ~w is being deleted now!",[?MODULE]),
    % Quite often the destructor does not need to modify the state of
    % the instance:
    State.

InstanceToDelete ! {synchronous_delete,self()},
% Then the caller can block as long as the deletion did not occur:
receive
  {deleted,InstanceToDelete} ->
      doSomething()
end.

Passive Instances

A passive instance is an instance of a WOOPER class that is not powered by a dedicated (Erlang) process: it is just a mere (opaque) term, a pure data-structure that holds the state [20] of that instance, and that is returned to the process having created that instance (which can then do whatever it wants with it - most probably store it as a "super attribute").

As a consequence, such a passive instance will not be able to perform any spontaneous behaviour on its own, or to have its member methods triggered by other processes. However most operations that can be done on "standard" (active) WOOPER instances can also be done on passive ones: like their active counterparts, they are constructed thanks to, well, one of the constructors defined by their class, they are destructed thanks to, well, their destructor, and in-between they will retain their inner state and be able to execute any request or oneway triggered by the process holding that term (and of course any underlying multiple inheritance will be respected).

Triggering a method onto a passive instance will result in a relevant function to be evaluated, not involving any message.

To create a passive instance, the new_passive operator shall be used, like in:

MyPassiveCat = class_Cat:new_passive(_Age=2, female, _Fur=brown, _Whiskers=white)

Then methods can be triggered on it, like in:

{WhiskerCat,white} = wooper:execute_request(MyPassiveCat, getWhiskerColor),
OlderCat = wooper:execute_oneway(WhiskerCat, declareBirthday),
RedCat = wooper:execute_oneway(OlderCat, setFurColor, red),
[...]

Note that, in addition to execute_request/{2,3}, execute_const_request/{2,3} are available; the latter return only the request result, as the state of the passive instance shall be constant (this is checked in debug mode).

Symmetrically, in addition to execute_oneway/{2,3}, execute_const_oneway/{2,3} are available even though their use is less common.

Until, finally:

wooper:delete_passive(RedCat).

Types may be defined in order to clarify the fact that a term corresponds to a (WOOPER) passive instance.

For example, for any kind of instance owning a passive calendar instance (created with, say, class_Calendar:new_passive/2), one could define and use, as attribute type [21]:

-type calendar_passive() :: wooper:passive_instance().

See the passive_instance_test module for more details about passive instances.

Serialisation

WOOPER offers a rather complete support for serialisation and deserialisation, so that instances can be written to and read from a series of bytes (this can be a WSF file, standing for WOOPER Serialisation File, a network stream, etc.).

For that the class_Serialisable interface provides all default yet overridable primitives, including:

• "serialisation hooks" (e.g. the onPreSerialisation/2 request), meant to accommodate any class-specific transformation that shall happen prior to each operation
• entry transformers, that are generally specific to a project but transverse to most if not all its classes, so that values of attributes can be recursively scanned for transient terms (like a PID, a reference), which are generally replaced with restoration markers at serialisation time, and recreated appropriately at deserialisation time

The usual variations (e.g. deserialisations may be synchronous or not, linked or not) of operations are supported.

Care as been taken so that these operations are done:

• generically: only the class-specific transformations are left to implement, in well-defined hooks, with relevant helpers already available (e.g. with examples of entry transformers)
• safely: optional checking that no transient term is still present in attribute values that are ready for serialisation, and that no restoration marker remains once a deserialised instance is ready
• efficiently: operations are intensely concurrent (each instance takes care of itself as much as possible), and by default storage is done in a compact, binary form

In practice, the Serialisable interface is defined in class_Serialisable.{hrl,erl}, and the extended features are implemented in the wooper_serialisation module. The serialisable_test test module showcases various examples, which involve the (serialisable) class_Reptile module.

Hot Code Update

The objective here is to be able to update classes at runtime whereas the program is still running, and to have their instances adapt in terms of state and behaviour to the corresponding new versions. Hot code reloading is typically useful in the case of always-available applications (never-stopping services), where bug fixes and additional features have to be deployed in spite of the continuous operation.

WOOPER offers such features, based on the Upgradable trait, implemented by the class_Upgradable interface.

An update protocol is proposed, with all support defined so that, for a given class that shall be updated (i.e. whose version must be either upgraded or downgraded):

1. all its instances are synchronously frozen first, to avoid that ongoing method calls experience code discrepancies
2. then the module corresponding to that class is reloaded (possibly after having been recompiled), being soft-purged (and possibly hard-purged if needed)
3. then all its instances perform (concurrently) any state update that they need in order to support the new version

In practice, for a given class (e.g. class_TestUpgradable), various versions thereof may be introduced over time (e.g. 1.2.3, then 1.2.4). Each version of a given class is free to override the default implementations of the upgradeVersion/4 and downgradeVersion/4 methods, as inherited from the class_Upgradable interface, in order to account for all changes introduced between two versions (e.g. attributes being added or removed, changing types, having their value transformed).

Refer to class_Upgradable_test for a full test thereof.

Helper vs Static

In the context of a class, one may wonder what is the difference between an exported helper function and a static method?

In terms of actual runtime evaluation, none.

In terms of source code, there is little difference: the former just has to use the wooper:return_static/1 to terminate its clauses and, should it use a type spec, this one should specify a return type based on return_static/1.

In terms of semantics, there are more differences: a static method is meant to stand by itself, whether or not an instance of that class exists, and to provide higher-level services.

On the contrary, an exported helper function is just a convenience for code-reuse, a means of sharing code between classes. Typically it centralises code of use by multiple methods, which often results in such an helper to have as a parameter a State variable (preferably listed last among its parameters, for clarity/uniformity) - whereas this cannot happen with static methods.

Calling a Method Clause from Another

Sometimes, defining a clause based on the result of another one (of the same function) proves convenient. With methods, there are different ways to do so, some better than others.

For example, let's suppose we defined this (non-const) request:

-spec getPriceFor(wooper:state(),string()) ->
        request_return(price()).
getPriceFor(State,ArticleStringDescription) ->
  {Price,NewState} = [...some code...]
  wooper:return_state_result(NewState,Price).

Now, we would like to support article descriptions being also possibly binary strings, without having to bother introducing a new price-establishing intermediary function (such as the foo/2 one, below) that would be common to the two corresponding clauses, like in:

getPriceFor(State,ArticleStringDescription) ->
       when is_list(ArticleStringDescription) ->
  {Price,NewState} = foo(ArticleStringDescription,State),
  wooper:return_state_result(NewState,Price);

getPriceFor(State,ArticleBinDescription)
       when is_binary(ArticleBinDescription) ->
  {Price,NewState} = foo(binary_to_list(ArticleBinDescription),
                         State),
  wooper:return_state_result(NewState,Price).

% Too cumbersome to define an extra function such as:
foo(ArticleStringDescription,State)->
  [...some code...]

So our first impulse would be to write instead something like:

% (same clause)
getPriceFor(State,ArticleStringDescription) ->
       when is_list(ArticleStringDescription) ->
  {Price,NewState} = [...some code...]
  wooper:return_state_result(NewState,Price);

% Added clause:
getPriceFor(State,ArticleBinDescription) ->
       when is_binary(ArticleBinDescription) ->
  getPriceFor(State,
      binary_to_list(ArticleBinDescription)).

However this would not be correct, as the second clause lacks a terminator, and WOOPER does not accept that (it might be the sign that the developer believes he is writing an helper function).

So we would like to use wooper:return_state_result/2 for the second clause as well, however we shall then have a state and a price to feed this terminator. How can we obtain them from the presumably opaque term returned by the wooper:return_state_result/2 call of the first clause?

The answer is quite simple: all WOOPER method terminators being actually no-op, they are replaced at compilation-time by the actual terms they were given.

So a terminator taking only a state as parameter is replaced literally by this state (e.g. wooper:return_state(FooState) is actually FooState), while one taking two returns a pair (e.g. wooper:return_state_result(FooState,Res) is actually {FooState,Res}). No black magic here!

Therefore the implementation we target could be best [22] written as:

% (same clause)
getPriceFor(State,ArticleStringDescription) ->
        when is_list(ArticleStringDescription) ->
   {Price,NewState} = [...some code...]
   wooper:return_state_result(NewState,Price);

 % Added clause:
 getPriceFor(State,ArticleBinDescription)
        when is_binary(ArticleBinDescription) ->
   {NewState,Price} = getPriceFor(State,
       binary_to_list(ArticleBinDescription)),
   wooper:return_state_result(NewState,Price).

Integrated Call APIs

Methods Not Returning Anything of Interest

Not all functions or static methods (or even requests) are pure, and sometimes only the side-effects of their execution are of interest, in which case nothing relevant may have to be returned [23].

For such needs, our Myriad base layer introduced the opaque pseudo-builtin type void() (nothing fancy), which is to be used by WOOPER methods as well.

Should one need a value of the void/0 type, we recommend using the void atom.

As a result (pun!), one may define:

-spec stop() -> static_return(void()).
stop() ->
  [...] % Do some side-effects
  wooper:return_static(void).

Introducing specific method terminators to convey that meaning would have been possible, yet multiplying the syntactical constructs would probably hurt the terseness of the underlying language.

However, as, fairly frequently, static methods have nothing meaningful to return, the wooper:return_static_void/0 method terminator and its spec-level counterpart static_void_return() type have been introduced [24].

Methods Not Returning

Some static methods may not return (see class_Serialisable:deserialise/4 for an example thereof).

Then their type specification shall use static_no_return() and each of their clause shall end with wooper:no_return_static().

Exception-Throwing Methods

A clause of a method may simply always throw an exception, and WOOPER will manage it automatically if possible.

More precisely, such a clause is considered licit yet not giving information about the method type. So, should there be other, non-throwing clauses, WOOPER will still be able to identify the nature of the method.

Otherwise (all clauses always throw), the class developer will have to give a hint about the actual nature of that function - thanks to a type specification.

For example, if defining the API of an abstract class (say, an AbstractShape class) whereas, for a given method signature (e.g. getArea/1), there is no meaningful default implementation, one may for example write:

getArea(_State) ->
    % For an abstract shape, no possible definition;
    % so catching any child class not overriding it,
    % thanks to:
    %
    throw(not_overridden).

However, from the point of view of WOOPER, getArea/1, short of using any method terminator, can be of any nature (for example a method or an helper function). WOOPER will then request the developer to clarify this ambiguity by adding a type spec, such as:

-spec getArea(wooper:state()) -> const_request_return(area()).

This will be sufficient for WOOPER.

In other related cases, it may be convenient instead to centralise the management of a range of failures in specific helper functions that always throw (such a function never returns), like in:

manage_foobar_failure(X,Y) ->
    [...]
    throw({foobar_failed,{X,Y}}).

Writing a method relying on such an helper function could be:

doSomething(State,A) ->
    case foobar(A,State) of

       {value,Result} ->
           wooper:const_return_result(Result);

       {error,Error} ->
           manage_foobar_failure(A,Error)

    end.

The problem is that this call to manage_foobar_failure/2 does not include a method terminator, and thus this branch would be, from the WOOPER point of view, the one of an helper function, thus clashing with the other branches (here telling it is a const request).

A solution could be to write instead:

[...]
        {error,Error} ->
            Dummy = manage_foobar_failure(A,Error),
            wooper:const_return_result(Dummy)

but that resulting code would not be that satisfactory (a bit ugly, not so readable).

So, instead, WOOPER introduced the throwing/1 method terminator, allowing the following, clearer, more elegant, code:

[...]
        {error,Error} ->
            wooper:throwing( manage_foobar_failure(A,Error) )

delete_any_instance_referenced_in/2

When an attribute contains either a single instance reference (i.e. the PID of the corresponding process) or a list of instance references, this WOOPER-defined helper function will automatically delete (asynchronously) these instances, and will return an updated state in which this attribute is set to undefined.

This function is especially useful in destructors.

For example, if State contains:

• an attribute named my_pid whose value is the PID of an instance
• and also an attribute named my_pids containing a list of PID instances

and if the instance at hand that shall be deleted took ownership of these instances, then:

delete(State) ->
    TempState = wooper:delete_any_instance_referenced_in(State,my_pid),
    wooper:delete_any_instance_referenced_in(TempState,my_pids).

will automatically delete all these instances (if any) and return an updated state.

Then the destructors of the mother classes can be chained by WOOPER.

See also the various other helpers defined in wooper.erl.

EXIT Signals / Messages

A class instance may (if trapping EXIT signals) receive EXIT messages from other processes.

A given class can process these EXIT notifications:

• either by defining and exporting the onWOOPERExitReceived/3 oneway
• or by inheriting it

For example:

-spec onWOOPERExitReceived(wooper:state(),basic_utils:pid_or_port(),
           basic_utils:exit_reason()) -> const_oneway_return().
onWOOPERExitReceived(State,PidOrPort,ExitReason) ->
   io:format("MyClass EXIT handler ignored signal '~p' "
             "from ~w.~n", [ExitReason,PidOrPort]),
   wooper:const_return().

may result in an output like:

MyClass EXIT handler ignored signal 'normal' from <0.40.0>.

If no class-level onWOOPERExitReceived/3 oneway is available, the default WOOPER EXIT handler (namely wooper:default_exit_handler/3) will be used (it just performs console-based notification).

It will just notify the signal to the user, by displaying a message like:

WOOPER default EXIT handler for instance <0.36.0> of class class_Cat
  ignored signal 'normal' from <0.40.0>.

DOWN Messages for Process Monitors

A class instance may receive DOWN messages from other (monitored) processes.

A given class can process these DOWN notifications:

• either by defining and exporting the onWOOPERDownNotified/5 oneway
• or by inheriting it

If no class-level onWOOPERDownNotified/5 oneway is available, the default WOOPER DOWN handler (namely wooper:default_down_handler/5) will be used (it just performs console-based notification).

Note that DOWN messages shall not be mixed up with the nodedown messages of the next section.

Node Monitors

Quite similarly to EXIT messages, node monitors and nodeup / nodedown messages are also managed by WOOPER, see the onWOOPERNodeConnection/3 and onWOOPERNodeDisconnection/3 oneways.

Should these oneways be not available for the class at hand, the default WOOPER node handlers (namely wooper:default_node_up_handler/3 and default_node_down_handler/3 respectively) will be used (they just perform console-based notifications).

Note that nodedown messages shall not be mixed up with the DOWN messages of the previous section.

A bit of Introspection

Here are the class-level information that can be fetched from the name of a class (as a result they are static methods):

• get_superclasses/0 will return the (ordered) list of the declared direct mother classes of this class
• get_class_specific_attributes/0 will return the (in-order) list of declared class-specific attribute metadata, as a list of wooper_info:attribute_info/0 records, containing, for a given attribute: its name, type, qualifiers and textual description

For example:

class_Platypus:get_superclasses().
[class_Mammal,class_OvoviviparousBeing]

When having at hand the state of an instance (so either from its methods and/or for a passive instance), various helpers in the wooper module can be used (e.g. get_classname/1, get_all_superclasses/1, is_instance_of/2, check_instance_of/2, get_attribute_pairs/1, state_to_string/1, get_class_filename/1). They are mostly intended for testing, as a good OOP design generally does not rely on such primitives.

Developer Guidelines

-include("wooper.hrl").

-behaviour(supervisor_bridge).

% User API of the bridge (can be arbitrarily chosen, including of course the arity):
-export([start_link/2]).

% Callbacks of the supervisor_bridge behaviour:
-export([init/1, terminate/2]).

-define(bridge_name, ?MODULE).

start_link(X,Y) ->
  Z=f(X),
  % Supposing here that a local registration of the bridge is wanted:
  supervisor_bridge:start_link({local, ?bridge_name},
      _Module=?MODULE, _InitArgs=[Y,hello,Z]).

-spec init( list() ) -> { 'ok', pid(), BridgeState :: term()}
      | 'ignore' | {'error', Error :: term()}.
init(_Args=[_A, Atom, B]) ->
  % No synchronous creation supposed useful here:
  MyFoobarInstancePid = class_Foobar:new_link(Atom,B),

  InitialBridgeState = {MyFoobarInstancePid, Atom},

  {ok, MyFoobarInstancePid, InitialBridgeState}.

terminate(Reason, _BridgeState={FoobarPid, _Atom}) ->
  % No synchronicity especially needed:
  FoobarPid ! delete.

WOOPER API

One can browse the WOOPER API documentation. WOOPER being, in some way, a dialect deriving from Erlang (hence closer to a language of its own than to a pure library), such an API documentation is most probably less useful than counterpart ones made for libraries like Myriad.

The next level of information is simply to read the corresponding source files, which are intensely commented and generally straightforward.

Class Developer Cheat Sheet

When specifying a class: -module(class_Foobar).

Any description thereof: -define(class_description,"Class for...").

When specifying its superclasses: -define(superclasses,[A,B]).

When specifying its class attributes: -define(class_attributes,[ATTR1,ATTR2,...])

A given ATTRn may be one of:

• {Name,Type,QualifierInfo,Description}
• {Name,Type,Description}
• {Name,Description}
• Name

QualifierInfo can be, for example, public, or [private,const].

All member methods have State for initial parameter, and are expected to return at least a (possibly const) state.

When defining a request:

• its spec should rely, for its return type, either on request_return(T()) or on const_request_return(T())
• each of its clause should terminate with either wooper:return_state_result(S,R) or wooper:const_return_result(R)

When defining a oneway:

• its spec should rely, for its return type, either on oneway_return() or on const_oneway_return()
• each of its clause should terminate with either wooper:return_state(S) or wooper:const_return()

When defining a static method:

• its spec should rely, for its return type, either on static_return(T()) or on static_void_return()
• each of its clause should terminate with wooper:return_static(R) or with wooper:return_static_void()

Finding it difficult not to mix the keywords for spec return types (e.g. request_return/1) and method terminators (e.g. wooper:return_state_result/2)?

A mnemonic could be that a spec return type designates a returned term (hence for example a request_return/1 - more generally such types always end with _return) whereas a method terminator designates an action (returning a state and a result, hence to wooper:return_state_result/2 for example).

Source Editors

We use Emacs but of course any editor will be fine.

For Nedit users, a WOOPER-aware nedit.rc configuration file for syntax highlighting (on black backgrounds), inspired from Daniel Solaz's Erlang Nedit mode, is available.

Similarity With Other Languages

WOOPER is in some ways adding features quite similar to the ones available with other languages, including Python (simple multiple inheritance, implied self/State parameter, attribute dictionaries/associative tables, etc.) while still offering the major strengths of Erlang (concurrency, distribution, functional paradigm) and not hurting too much the overall performances (mainly thanks to the prebuilt attribute and method tables).

WOOPER limitations

Actually no significant implementation shortcoming has been identified.

The main limitations that existed beforehand were (from the most recently alleviated to the earlier ones):

• the per-instance memory footprint has been reduced by sharing the "virtual table" of a given class between all its instances, thanks to persistent_term
• the efficiency of the per-instance associative table to store the attribute values has been improved by switching from our hashtable implementation to a map-based one
• the macro-based constructor declarations were too cumbersome and limiting (e.g. a single constructor per class was supported); this is fully addressed thanks to the WOOPER parse transform now

We expect the now default JIT compilation to benefit a lot to WOOPER, with no change having to be operated at its level.

As always, there is certainly room for improvement, to grind a bit more runtime performances and/or to further reduce the per-instance memory footprint. Profiling actions welcome!

Class implementations

• class_Creature.erl
• class_ViviparousBeing.erl
• class_OvoviviparousBeing.erl
• class_Mammal.erl
• class_Reptile.erl
• class_Cat.erl
• class_Platypus.erl

Tests

Here are a few examples of tests:

• class_Creature_test.erl
• class_ViviparousBeing_test.erl
• class_OvoviviparousBeing_test.erl
• class_Mammal_test.erl
• class_Reptile_test.erl
• class_Cat_test.erl
• class_Platypus_test.erl

To run a test (e.g. class_Cat_test.erl), when WOOPER has already been compiled, one just has to enter, from the corresponding directory: make class_Cat_run.

Debug Mode

We recommend that, as a WOOPER user, one enables its debug mode when developing (ensure in GNUmakevars.inc that ENABLE_DEBUG has been set to true - which is the case by default), as it may catch various user errors more easily (not only WOOPER-internal errors, but also, and most importantly, any user-originating mistake).

Then only, once one's code is mature enough, this debug mode may be disabled in order to obtain best performances.

"No attribute declaration found" whereas a class_attributes define exists

Most probably that your -define(class_attributes,[...]). define happens after the WOOPER header include.

The correct order is:

-define(class_attributes,[
            ATTR_DECL1,
            ATTR_DECL2,
            [...]
            ATTR_DECLN]).
[...]
-include("wooper.hrl").
[...]

Compilation Error Pointing to wooper_for_classes.hrl

As the comment in wooper_get_class_attributes/0 (in said header file) hints, the class_attributes define in the class at hand is most probably incorrect (syntax error).

The compilation error message should help; if it is syntax error before: '|', a union type for an attribute must have been defined with |, instead of with the union variadic pseudo-operator. See the section about attribute declaration for more details.

General Case

startBarkingAt(State,Duration,ListenerPID) -> ...

MyDogPid ! {startBarkingAt,[MyDuration,self()]}

MyDogPid ! {startBarkingAt,MyDuration,self()}

Error in process <0.43.0> on node 'XXXX' with exit value:
  {badarg,[{class_Dog,wooper_main_loop,1}]}.

Prerequisites

This OOP layer, Ceylan-WOOPER, relies (only) on:

• Erlang
• the Ceylan-Myriad base layer

We prefer using GNU/Linux, sticking to the latest stable release of Erlang, and building it from sources, thanks to GNU make.

Refer to the corresponding Myriad prerequisite section for more precise guidelines, knowing that Ceylan-WOOPER does not need modules with conditional support such as crypto or wx.

Using Cutting-Edge GIT

This is the installation method that we use and recommend; the WOOPER master branch is meant to stick to the latest stable version: we try to ensure that this main line always stays functional (sorry for the pun). Evolutions are to take place in feature branches and to be merged only when ready.

As a result, once a proper Erlang version is available, the Ceylan-Myriad repository should be cloned and built, before doing the same with the Ceylan-WOOPER repository, like in:

$ git clone https://github.com/Olivier-Boudeville/Ceylan-Myriad myriad
$ cd myriad && make all && cd ..
$ git clone https://github.com/Olivier-Boudeville/Ceylan-WOOPER wooper
$ cd wooper && make all

Using OTP-Related Build/Runtime Conventions

As discussed for Myriad, we added the (optional) possibility of generating a WOOPER OTP application out of the build tree (obtained thanks to the method described in the previous section), ready to be integrated into an (OTP) release. For that we rely on rebar3, relx and hex.

OTP conventions mandate using:

-include_lib("wooper/include/wooper.hrl").

rather than:

-include("wooper.hrl").

Unlike Myriad, which is an OTP library application, WOOPER is an OTP active application, meaning the reliance on an application that can be started/stopped (wooper_app), a root supervisor (wooper_sup) and a class manager that is a background server process (gen_server) in a supervision tree.

$ git clone https://github.com/Olivier-Boudeville/Ceylan-WOOPER.git wooper
$ cd wooper
$ rebar3 compile

$ make rebar3-application
$ make rebar3-release

$ cd test
$ make wooper_otp_application_run
       Running unitary test wooper_otp_application_run (third form)
            from wooper_otp_application_test

--> Testing module wooper_otp_application_test.

Starting the WOOPER application.
[debug] Starting WOOPER application (type: normal, start arguments: []).
[debug] Starting the WOOPER root supervisor.
[debug] Initializing the WOOPER root supervisor (args: []).
[debug] Starting and linking the WOOPER class manager.
[debug] WOOPER class manager created, as <0.87.0>.
WOOPER version: {2,0,5}.
Class filename corresponding to 'class_Tiger': 'class_Tiger.erl'.
Stopping the WOOPER application.
[debug] Stopping WOOPER application (state: []).
Successful end of test of the WOOPER application.
=INFO REPORT==== 19-Jul-2019::22:53:28.243821 ===
   application: wooper
   exited: stopped
   type: temporary
=INFO REPORT==== 19-Jul-2019::22:53:28.260437 ===
   application: myriad
   exited: stopped
   type: temporary

--> Successful end of test.

(test finished, interpreter halted)

Using Hex

Hex packages for WOOPER used to be published for most versions, yet finally our workflow does not rely on Hex, so we do not update the Hex packages anymore. Just drop us an email if needing a recent one.

For more details, one may have a look at:

• rebar.config.template, the general rebar configuration file used when generating the WOOPER OTP application and release (implying the automatic management of Myriad)
• rebar-for-hex.config.template, to generate a corresponding Hex package for WOOPER (whose structure and conventions is quite different from the previous OTP elements)
• rebar-for-testing.config.template, the simplest test of the previous Hex package: an empty rebar project having for sole dependency that Hex package

Testing WOOPER

Once Myriad and WOOPER itself have been built (for that refer to either Using Cutting-Edge GIT or Using Rebar3), just run from the root directory of WOOPER:

$ make test

The testing shall complete successfully (if it is not the case, see our support section).

Version 2.0 [current stable]

Released officially on Sunday, February 3, 2019 initially, and consistently improved since then.

It has been a large rewriting of this layer, with much improvements notably:

• multiple different-arity constructors per class are supported now
• no more wooper_construct_parameters, longer wooper_construct_export or wooper_construct_export defines
• automatic detection and export of constructors, any destructor and methods
• WOOPER method terminators introduced (e.g. wooper:return_state_result/2, instead of the wooper_return_state_result macro)
• the class_attributes optional parse attribute define introduced (-define(class_attributes,[...]).
• execute*With renamed as execute*As (clearer)
• convenience method wrappers such as wooper:execute_request/3 have their parameters reordered (target - either a PID or a passive instance - comes first now)
• passive instances supported (still a bit experimental, not used a lot, yet working)

More generally, many macros and definitions in the WOOPER header files moved to code generated thanks to a parse-transform.

Although this version does not share any code with the various experiments and candidate 2.0 versions that had been previously developed (thanks at least to Ulf and Nicolas in 2010, and to Enrique and Roland in 2013, both operating at that time on the so-called Zero-Overhead WOOPER version), these preliminary works surely helped defining the API that we deem suitable now, and that we implemented in the current version.

Version 1.x

Since 2016 we switched back to a "rolling version", not really defining specific release milestones.

Many minor improvements integrated, API enriched in a backward compatible manner.

These versions have been pretty stable very soon, and did the job for nearly a decade (2008-2018), during which various attempts of radical improvements were performed.

Version 1.0

Countless improvements have been integrated in the course of the use of WOOPER, which has been now been stable for years.

The main change since the 0.4 version is the use of the newly-introduced map Erlang datatype, resulting in the hashtable module being replaced by the map_hashtable. They obey to the same API and the table pseudo-type abstracts out the actual choice in that matter (it is transparently parse-transformed into the currently-retained datatype).

Version 0.4

It is mainly a BFO (Bug Fixes Only) version, as functional coverage is pretty complete already.

Main changes are:

• debug mode enhanced a lot: many checkings are made at all fronteers between WOOPER and either the user code (messages) or the class code (constructors, methods, destructor, execute requests); user-friendly explicit error messages are displayed instead of raw errors in most cases; is_record used to better detect when an expected state is not properly returned
• wooper_result not appended any more to method returns in debug mode
• release mode tested and fixed
• exit replaced by throw, use of newer and better try/catch instead of mere catch
• destructor chained calls properly fixed this time
• delete_any_instance_referenced_in/2 added, wooper:return_state_* macros simplified, remote_* bug fixed

Version 0.3

Released on Wednesday, March 25, 2009.

Main changes are:

• destructors are automatically chained as appropriate, and they can be overridden at will
• incoming EXIT messages are caught by a default WOOPER handler which can be overridden on a per-class basis by the user-specified onWOOPERExitReceived/3 method
• direct method invocation supported, thanks to the executeRequest and executeOneway constructs, and wooper_result no more appended to the result tuple
• synchronous spawn operations added or improved: synchronous_new/synchronous_new_link and al; corresponding template updated
• state management enriched: popFromAttribute added
• all new variations on remote nodes improved or added
• major update of the documentation

Version 0.2

Released on Friday, December 21, 2007. Still fully functional!

Main changes are:

• the sender PID is made available to requests in the instance state variable (see request_sender member, used automatically by the getSender/0 macro)
• runtime errors better identified and notified
• macros for attribute management added, existing ones more robust and faster
• fixed a potential race condition when two callers request nearly at the same time the WOOPER class manager (previous mechanism worked, class manager was a singleton indeed, but second caller was not notified)
• improved build (Emakefile generated), comments, error output
• test template added
• documentation updated

Version 0.1

Released on Sunday, July 22, 2007. Already fully functional!

General Principles

my_server(State) ->
  receive
    {command,{M,P}} ->
      NewState = execute_command(State,M,P),
      my_server(NewState)
  end.

Method Virtual Table

Attribute Table

This is another associative table, this time necessarily per-instance.

Keys are attribute names of that instance, values are the corresponding attribute values.

It allows a simple, seamless yet efficient access to all data members, including inherited ones.