\section{Chare Objects}

\index{chare}Chares are concurrent objects with methods that can be invoked
remotely. These methods are known as \index{entry method}entry methods. All
chares must have a constructor that is an entry method, and may have any
number of other entry methods. All chare classes and their entry methods are
declared in the interface (\texttt{.ci}) file:

\begin{alltt}
    chare ChareType
    \{
        entry ChareType(\uw{parameters1});
        entry void EntryMethodName(\uw{parameters2});
    \};
\end{alltt}

Although it is {\em declared} in an interface file, a chare is a \CC{} object
and must have a normal \CC{} {\em implementation} (definition) in addition. A
chare class {\tt ChareType} must inherit from the class {\tt CBase\_ChareType},
which is a special class that is generated by the \charmpp translator from the
interface file. Note that \CC{} namespace constructs can be used in the
interface file, as demonstrated in \examplerefdir{namespace}.

To be concrete, the \CC{} definition of the \index{chare}chare above might have 
the following definition in a \texttt{.h} file:

\begin{alltt}
   class ChareType : public CBase\_ChareType \{
       // Data and member functions as in C++
       public:
           ChareType(\uw{parameters1});
           void EntryMethodName2(\uw{parameters2});
   \};
\end{alltt}

\index{chare}
Each chare encapsulates data associated with medium-grained units of work in a
parallel application.
Chares can be dynamically created on any processor; there may
be thousands of chares on a processor. The location of a chare is
usually determined by the dynamic load balancing strategy. However,
once a chare commences execution on a processor, it does not migrate
to other processors\footnote{Except when it is part of an array.}.  
Chares do not have a default ``thread of
control'': the entry methods \index{entry methods} in a
chare execute in a message driven fashion upon the arrival of a 
message\footnote{Threaded methods augment this behavior since they execute in
a separate user-level thread, and thus can block to wait for data.}.

The entry method definition specifies a function that is executed {\em without
interruption} when a message is received and scheduled for processing. Only one
message per chare is processed at a time.  Entry methods are defined exactly as
normal \CC{} function members, except that they must have the return value
\kw{void} (except for the constructor entry method which may not have a return
value, and for a {\em synchronous} entry method, which is invoked by a {\em
threaded} method in a remote chare). Each entry method can either take no
arguments, take a list of arguments that the runtime system can automatically
pack into a message and send (see section~\ref{entry}), or take a single
argument that is a pointer to a \charmpp message (see section~\ref{messages}).

A chare's entry methods can be invoked via {\it proxies} (see
section~\ref{proxies}). Proxies to a chare of type {\tt chareType} have type
{\tt CProxy\_chareType}. By inheriting from the CBase parent class, each chare
gets a {\tt thisProxy} member variable, which holds a proxy to itself. This
proxy can be sent to other chares, allowing them to invoke entry methods on this
chare.

\zap{
Each chare instance is identified by a {\em handle} \index{handle}
which is essentially a global pointer, and is unique across all
processors.  The handle of a chare has type \kw{CkChareID}.  The
variable \kw{thishandle} holds the handle of the
chare whose entry function or public function is currently executing.
\kw{thishandle} is a public instance variable of the chare object
which is inherited from the system-defined superclass
\kw{CBase}\_\uw{ClassType}.
Following the older syntax, chares are also allowed to inherit directly
for the superclass \kw{Chare} instead of \kw{CBase}\_\uw{ClassType}, although
this form is not suggested.
\kw{thishandle} can be used to set fields in a message. This  
mechanism allows chares to send their handles to other chares.
}

\subsection{Chare Creation}

\label{chare creation}

Once you have declared and defined a chare class, you will want to create some
chare objects to use. Chares are created by the {\tt ckNew} method, which is a
static method of the chare's proxy class:

\begin{alltt}
   CProxy_chareType::ckNew(\uw{parameters}, int destPE);
\end{alltt}

The {\tt parameters} correspond to the parameters of the chare's constructor.
Even if the constructor takes several arguments, all of the arguments should be
passed in order to {\tt ckNew}. If the constructor takes no arguments, the
parameters are omitted. By default, the new chare's location is determined by
the runtime system. However, this can be overridden by passing a value for
{\tt destPE}, which specifies the PE where the chare will be created.

The \index{chare}chare creation method deposits the \index{seed}{\em seed} for
a chare in a pool of seeds and returns immediately. The \index{chare}chare will
be created later on some processor, as determined by the dynamic \index{load
balancing}load balancing strategy (or by {\tt destPE}).
When a \index{chare}chare is created, it is
initialized by calling its \index{constructor}constructor \index{entry
method}entry method with the parameters specified by {\tt ckNew}.

Suppose we have declared a chare class {\tt C} with a constructor that takes two
arguments, an {\tt int} and a {\tt double}.

\begin{enumerate}
\item{This will create a new \index{chare}chare of type \uw{C} on {\em any}
processor and return a proxy to that chare:}

\begin{alltt}
   CProxy_C chareProxy = CProxy_C::ckNew(1, 10.0);
\end{alltt} 

\item{This will create a new \index{chare}chare of type \uw{C} on processor
\kw{destPE} and return a proxy to that chare:}

\begin{alltt}
   CProxy_C chareProxy = CProxy_C::ckNew(1, 10.0, destPE);
\end{alltt}

\end{enumerate}

For an example of chare creation in a full application, see
\examplerefdir{fib} in the \charmpp software distribution, which
calculates fibonacci numbers in parallel.

\subsection{Method Invocation on Chares}

A message \index{message} may be sent to a \index{chare}chare through a proxy
object using the notation:

\begin{alltt}
    chareProxy.EntryMethod(\uw{parameters})
\end{alltt}

This invokes the entry method \uw{EntryMethod} on the chare referred
to by the proxy \uw{chareProxy}. This call
is asynchronous and non-blocking; it returns immediately after sending the
message. 


\subsection{Local Access}

You can get direct access to a local chare using the
proxy's \kw{ckLocal} method, which returns an ordinary \CC\ pointer
to the chare if it exists on the local processor, and NULL otherwise.

\begin{alltt}
    C *c=chareProxy.ckLocal();
    if (c==NULL) {
        // object is remote; send message
    } else {
        // object is local; directly use members and methods of c
    }
\end{alltt}

