<section id="r_prop">
<title/The class <<OZ_Propagator>>/

<p>
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.
<p>

<!-- ********************************************************************** -->

<subsection id="r_prop.constr">
<title/Constructor and Destructor Member Functions/
<p>

<List proglang=cc>

<Entry class="default constructor"><<OZ_Propagator>>
<Index class=proglang><<OZ_Propagator>></Index>
<Synopsis> <<OZ_Propagator(void);>>

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


<Entry class="virtual destructor"><<~OZ_Propagator>>
<Index class=proglang><<OZ_Propagator>><And><<~OZ_Propagator>></Index>
<Synopsis> <<virtual ~OZ_Propagator();>>

<Item> 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.

</List> 

<!-- ********************************************************************** -->

<subsection id="r_prop.operator">
<title/Operator Member Functions/
<p>


<List proglang=cc>

<Entry class="static operator member function"><<new>>
<Index class=proglang><<OZ_Propagator>><And><<new>></Index>
<Synopsis> <<static void * operator new(size_t);>>

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

<Entry class="static operator member function"><<delete>>
<Index class=proglang><<OZ_Propagator>><And><<delete>></Index>
<Synopsis> <<static void operator delete(void *, size_t);>>

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

</List>

<!-- ********************************************************************** -->

<subsection id="r_prop.provided">
<title/Provided Member Functions/
<p>

<List proglang=cc>

<Entry class="member function"><<mayBeEqualVars>>
<Index class=proglang><<OZ_Propagator>><And><<mayBeEqualVars>></Index>
<Synopsis> <<OZ_Boolean mayBeEqualVars(void);>>

<Item> 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 <Ptr.extern to="ozdoc:cpitut"
key="u_advanced.detect"> for details.


<Entry class="member function"><<replaceBy>>
<Index class=proglang><<OZ_Propagator>><And><<replaceBy>></Index>
<Synopsis> <<OZ_Return replaceBy(OZ_Propagator * p);>>

<Item> This member function replaces the current propagator (&ie; 
<<*this>>) by the propagator <<p>>.


<Entry class="member function"><<replaceBy>>
<Index class=proglang><<OZ_Propagator>><And><<replaceBy>></Index>
<Synopsis> <<OZ_Return replaceBy(OZ_Term a, OZ_Term b);>>

<Item> This member function replaces the current propagator (&ie;
<<*this>>) by the equality constraint between <<a>> and <<b>>.
<p>
Caution: before <<replaceBy>> can be called, for all <<x>> of type
<<OZ_FDIntVar>> the member function <<x.leave()>> has to be called.
<p>

<Entry class="member function"><<replaceByInt>>
<Index class=proglang><<OZ_Propagator>><And><<replaceByInt>></Index>
<Synopsis> <<OZ_Return replaceByInt(OZ_Term v, int i);>>

<Item> This member function replaces the current propagator (&ie;
<<*this>>) by the equality constraint between <<v>> and <<i>>.


<Entry class="member function"><<postpone>>
<Index class=proglang><<OZ_Propagator>><And><<postpone>></Index>
<Synopsis> <<OZ_Return postpone(void);>>

<Item> This member function (usually in conjunction with the
<<return>> statement) causes the execution of the propagator to be
postponed, &ie;  the propagator is immediately switched to <<runnable>>
and put at the end of the thread queue.


<Entry class="member function"><<imposeOn>>
<Index class=proglang><<OZ_Propagator>><And><<imposeOn>></Index>
<Synopsis> <<OZ_Boolean imposeOn(OZ_Term t);>>

<Item> This member function imposes the current propagator (&ie; 
<<*this>>}) on <<t>>. If the imposition was successful, &ie;, <<t>>
refers to a variable, <<OZ_TRUE>> is returned, otherwise <<OZ_FALSE>>.


<Entry class="member function"><<addImpose>>
<Index class=proglang><<OZ_Propagator>><And><<addImpose>></Index>
<Synopsis> 
<<<
void addImpose(OZ_FDPropState s, OZ_Term v);
void addImpose(OZ_FSetPropState s, OZ_Term v);
>>>

<Item> 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.
<p>

<Entry class="member function"><<impose>>
<Index class=proglang><<OZ_Propagator>><And><<impose>></Index>
<Synopsis> <<void impose(OZ_Propagator * p);>>

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

<Entry class="constant member function"><<toString>>
<Index class=proglang><<OZ_Propagator>><And><<toString>></Index>
<Synopsis><<char * toString(void) const;>>

<Item> Returns a textual representation of the propagator pointing to
a static array of <<char>>s.

</List>

<!-- ********************************************************************** -->

<subsection id="r_prop.todefine">
<title/Member Functions to be Defined by the Programmer/
<p>
The member functions in this section are purely virtual, &ie;, a class
inheriting from <<OZ_Propagator>> <em/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.
<p>

<List proglang=cc>

<Entry class="pure virtual member function"><<sizeOf>>
<Index class=proglang><<OZ_Propagator>><And><<sizeOf>></Index>
<Synopsis> <<virtual size_t sizeOf(void) = 0;>>

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


<Entry class="pure virtual member function"><<sClone>>
<Index class=proglang><<OZ_Propagator>><And><<sClone>></Index>
<Synopsis> <<virtual void sClone(void) = 0;>>

<Item> 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
<ptr to="r_aux">) and possibly, copy dynamically allocated extensions
of the object's state. Further details on that issue can be found in
<Ptr.Extern to="ozdoc:cpitut" key="u_advanced.redundant">.
<p>

<Entry class="pure virtual member function"><<gCollect>>
<Index class=proglang><<OZ_Propagator>><And><<gCollect>></Index>
<Synopsis> <<virtual void gCollect(void) = 0;>>

<Item> 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 <ptr to="r_aux">) and possibly, copy
dynamically allocated extensions of the object's state. Further
details on that issue can be found in <Ptr.Extern to="ozdoc:cpitut"
key="u_advanced.redundant">.
<p>

<Entry class="pure virtual member function"><<propagate>>
<Index class=proglang><<OZ_Propagator>><And><<propagate>></Index>
<Synopsis> <<virtual OZ_Return propagate(void) = 0;>>

<Item> 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.


<Entry class="pure virtual member function"><<getParameters>>
<Index class=proglang><<OZ_Propagator>><And><<getParameters>></Index>
<Synopsis> <<virtual OZ_Term getParameters(void) const = 0;>>

<Item> 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.
<p>

<Entry class="pure virtual member function"><<getProfile>>
<Index class=proglang><<OZ_Propagator>><And><<getProfile>></Index>
<Synopsis> <<virtual OZ_PropagatorProfile getProfile(void) const = 0;>>

<Item> 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).

</List>
