Class type Swarm.SWARM.core

class type core = object  end

The type of a resident core. The user of a Swarm should create objects whose type extends core and add them to the Swarm with the method t#shelter below. All the methods defined here are called at the appropriate times by the Swarm directly. The harness should probably not call these methods directly. Rather, go through the Swarm interface. The resident core can define additional methods which may be called externally.

method set_notifier : notifier_type -> unit

Called at the time of sheltering to set to notifier object which the resident core can use to communicate with the Swarm.

method reset_notifier : unit -> unit

This method should never be called - for use only by the Swarm internals.

method start : unit -> unit

Set the activity state to true. If there is any initialization, do it here. An inactive resident does not need to respond to click methods and most other methods.

method stop : unit -> unit

Set the activity state to false. Called when the Swarm is inactivated, resident removed or when the harness simply wants to.

method is_started : unit -> bool

Should return the activity state of the resident.

method get_projection : unit -> projection list

The Swarm calls this at the beginning of the life of the resident to inquire about the projections exported. This list should not change over the life of the resident.

method has_active : projection -> bool

r#has_active p should return true if the projection p on resident r has a marker which the Swarm should use for matching computation. A resident can change this activity state of projections at will. FIXME: Right now, there's no good method to inform the Swarm when this change happens, but the Swarm is constantly recalculating the matchings from scratch, so it doesn't matter. But in the future it will, though!

method get_full_marker : projection -> marker

r#get_full_marker p should return the full marker associated with projection p on resident r if that projection is active. If not, then it should raise No_matching_marker. The full marker will participate in the match finding activity orchestrated by the Swarm.

method get_submarker : projection -> matchinghalf -> submarker

FIXME: ...

method click : unit -> bool

The main time-wasting method! It is called repeatedly on an active resident core. The resident core should do whatever it needs to do in smallish chunks and return control to the Swarm. The method will be called again shortly if the return value is true. If it is false, the resident core will be put in hibernation. It will be automatically woken if a binding is attempted or broken or explicitly by another resident or the harness.

method unimate_dock : projection ->
       matchinghalf -> submarker -> bindhalf

The first phase of a binding confirmation. The second phase is either unimate_prop in case the binding is successful, or unimate_undock if it fails. The primary scenario is the following: dock is called on both residents, and prop (for propagate) is then called on both residents. In case the second dock fails, undock is called on the first resident. All the calls are made under the same lock. The prop calls can be executed as if they were click methods: they can trigger release, etc. The call format is r#unimate_dock p mh sm. p is the projection of r which is affected mh the matchinghalf on the side of r and mh the submarker on the other side. If the binding is not accepted, the method should raise Invalid_matchinghalf or No_matching_marker, as appropriate.

The return value should be a manufactured element of type bindhalf, which can carry any information that the resident core wishes to preserve and share with the other side, through the get_symmetric method on the notifier.

method unimate_undock : projection -> bindhalf -> unit

Called after unimate_dock in case the binding fails, to inform the resident core. The core should undo anything it has done during the docking phase.

method unimate_prop : projection ->
       bindhalf ->
       (< click : unit -> bool;
          get_full_marker : projection -> marker;
          get_projection : unit -> projection list;
          get_submarker : projection ->
                          matchinghalf -> submarker;
          has_active : projection -> bool; is_started : unit -> bool;
          reset_notifier : unit -> unit;
          set_notifier : notifier_type -> unit; start : unit -> unit;
          stop : unit -> unit;
          tarjoin : projection ->
                    bindhalf ->
                    'b ->
                    projection ->
                    bindhalf ->
                    joinmessage ->
                    ('b * projection * bindhalf) *
                    joinpart;
          tarsplit : projection ->
                     bindhalf ->
                     splitmessage ->
                     ('b * projection * bindhalf) *
                     ('b * projection * bindhalf) *
                     splitpart;
          unimate_dock : projection ->
                         matchinghalf ->
                         submarker -> bindhalf;
          unimate_prop : 'a;
          unimate_undock : projection -> bindhalf -> unit;
          unirelease : projection -> bindhalf -> unit; .. > as 'b)
       bindholder -> unit as 'a

Called after unimate_dock when the binding is successful, to confirm it. The bindhalf passed is that which was returned at docking. This method should never fail.

method unirelease : projection -> bindhalf -> unit

Called from the Swarm to release a binding, identified by the projection and the bindhalf passed as parameters. Should never fail. A release can be triggered by another resident or by the harness.

method tarsplit : projection ->
       bindhalf ->
       splitmessage ->
       ('b * projection * bindhalf) *
       ('b * projection * bindhalf) * splitpart

Called from the Swarm when a bound resident wants to split its opposite resident. tarsplit p b should return

(s1,
	p1, b1), (s2, p2, b2), splitf

, where p, b identify the projection to be split on the target resident; (s1, p1, b1) identify the new binding of the first half of the split binding, and similarly for the other index; and splitf is used to determine the new owner of each of the other bindings which the target resident may have. The Swarm will take care to add both new residents to itself and to remove the old target - however, the state should be already set, since no further method will be called on either the new residents or the old one. In particular, they should already be active.

method tarjoin : projection ->
       bindhalf ->
       'b ->
       projection ->
       bindhalf ->
       joinmessage ->
       ('b * projection * bindhalf) * joinpart