1.3 The class OZ_Propagator

## 1.3 The class `OZ_Propagator`

This class is the base class of all propagators to be implemented. Since this class is a virtual base class, it is not possible to create an instance of that class.

### 1.3.1 Constructor and Destructor Member Functions

`OZ_Propagator` [default constructor]

  > `OZ_Propagator(void);`

  This constructor is to be called whenever an instance of a class derived from `OZ_Propagator` is created.

`~OZ_Propagator` [virtual destructor]

  > `virtual ~OZ_Propagator();`

  This destructor is defined to be virtual to force the destructors in the derived classes to be virtual. This ensure that destroying a derived class results in calling the destructor of the derived class.

### 1.3.2 Operator Member Functions

`new` [static operator member function]

  > `static void * operator new(size_t);`

  This operator allocates the appropriate amount of heap memory when a propagator is created.

`delete` [static operator member function]

  > `static void operator delete(void *, size_t);`

  This operator deallocates the heap memory occupied by a propagator when it is destroyed.

### 1.3.3 Provided Member Functions

`mayBeEqualVars` [member function]

  > `OZ_Boolean mayBeEqualVars(void);`

  This member function returns `OZ_TRUE` if at least one variable the propagator was imposed on has been unified. Otherwise it returns `OZ_FALSE`. See Section 1.7.1 of ``The Mozart Constraint Extensions Tutorial'' for details.

`replaceBy` [member function]

  > `OZ_Return replaceBy(OZ_Propagator * p);`

  This member function replaces the current propagator (i. e. `*this`) by the propagator `p`.

`replaceBy` [member function]

  > `OZ_Return replaceBy(OZ_Term a, OZ_Term b);`

  This member function replaces the current propagator (i. e. `*this`) by the equality constraint between `a` and `b`.

  Caution: before `replaceBy` can be called, for all `x` of type `OZ_FDIntVar` the member function `x.leave()` has to be called.

`replaceByInt` [member function]

  > `OZ_Return replaceByInt(OZ_Term v, int i);`

  This member function replaces the current propagator (i. e. `*this`) by the equality constraint between `v` and `i`.

`postpone` [member function]

  > `OZ_Return postpone(void);`

  This member function (usually in conjunction with the `return` statement) causes the execution of the propagator to be postponed, i. e. the propagator is immediately switched to `runnable` and put at the end of the thread queue.

`imposeOn` [member function]

  > `OZ_Boolean imposeOn(OZ_Term t);`

  This member function imposes the current propagator (i. e. `*this`}) on `t`. If the imposition was successful, i. e., `t` refers to a variable, `OZ_TRUE` is returned, otherwise `OZ_FALSE`.

`addImpose` [member function]

  > > `void addImpose(OZ_FDPropState s, OZ_Term v);
  > > void addImpose(OZ_FSetPropState s, OZ_Term v);`

  These member functions add `v` to the parameters of the propagator to be imposed with next invocation of `OZ_Propagator::impose`. In case `v` does not denote a variable nothing happens. The value of `s` determines the event when the propagator is to be resumed.

`impose` [member function]

  > `void impose(OZ_Propagator * p);`

  This member function imposes the propagator `p` on the parameters collected by `addImpose`. The propagator is immediately switched to runnable, but not initially run.

`toString` [constant member function]

  > `char * toString(void) const;`

  Returns a textual representation of the propagator pointing to a static array of `char`s.

### 1.3.4 Member Functions to be Defined by the Programmer

The member functions in this section are purely virtual, i. e., a class inheriting from `OZ_Propagator` must define these functions, otherwise it is not possible to create instances of such a class. These pure virtual member functions make `OZ_Propagator` to an abstract base class.

`sizeOf` [virtual member function]

  > `virtual size_t sizeOf(void) = 0;`

  The implementation of this pure virtual function in a derived class `P` is supposed to return the size of an instance of `P`.

`sClone` [virtual member function]

  > `virtual void sClone(void) = 0;`

  The implementation of this pure virtual function in a derived class `P` is called during cloning and is supposed to apply to each data member of type `OZ_Term` the function `OZ_sCloneTerm` (see Section 1.9) and possibly, copy dynamically allocated extensions of the object's state. Further details on that issue can be found in Section 1.7.2 of ``The Mozart Constraint Extensions Tutorial''.

`gCollect` [virtual member function]

  > `virtual void gCollect(void) = 0;`

  The implementation of this pure virtual function in a derived class `P` is called during garbage collection and is supposed to apply to each data member of type `OZ_Term` the function `OZ_sCloneTerm` (see Section 1.9) and possibly, copy dynamically allocated extensions of the object's state. Further details on that issue can be found in Section 1.7.2 of ``The Mozart Constraint Extensions Tutorial''.

`propagate` [virtual member function]

  > `virtual OZ_Return propagate(void) = 0;`

  The implementation of this pure virtual function in a derived class `P` is supposed to implement the operational semantics of the propagator. The return value indicates the result of the computation to the emulator.

`getParameters` [virtual member function]

  > `virtual OZ_Term getParameters(void) const = 0;`

  The implementation of this pure virtual function in a derived class `P` is supposed to return the list (as Oz data structure) of `P`'s parameters. Nested parameter structures are to be represented as nested lists.

`getProfile` [virtual member function]

  > `virtual OZ_PropagatorProfile getProfile(void) const = 0;`

  The implementation of this pure virtual function in a derived class `P` is supposed to return the static profile member function used to get information about the state of a propagator class (for instance, the number of total invocations).