\subsection{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, and 
must be specified in the interface (\texttt{.ci}) file:

\begin{alltt}
chare ChareType
\{
    entry   ChareType             (MessageType1 *);
    entry   void EntryMethodName2 (MessageType2 *);
\};
\end{alltt}

A corresponding \index{chare}chare definition in the \texttt{.h} file would 
have the form:

\begin{alltt}
   class ChareType : public Chare [: superclass names] \{   
        // Data and member functions as in C++ 
        // One or more entry methods definitions of the form: 
   public: 
      ChareType(MessageType1 *MsgPointer) 
         \{ // C++ code block  \} 
      void EntryMethodName2(MessageType2 *MsgPointer) 
         \{ // C++ code block  \} 
   \};
\end{alltt}

\index{chare}
Chares are concurrent objects encapsulating medium-grained units of
work.  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) and they
must have exactly one argument which is a pointer to a message.

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
(it is inherited from the system-defined superclass for chares, \kw{Chare}).
\kw{thishandle} can be used to set fields in a message. This  
mechanism allows chares to send their handles to other chares.

\subsubsection{Chare Creation}
\label{chare creation}

First, a \index{chare}chare needs to be declared, both in \texttt{.ci} file and
in \texttt{.h} file, as stated earlier. The following is an example of
declaration for a \index{chare}chare of user-defined type \uw{C}, where \uw{M1}
and \uw{M2} are user-defined \index{message}message types, and \uw{someEntry}
is an entry method.

In the \texttt{mod.ci} file we have:

\begin{alltt}
module mod \{
  chare C \{
    entry C(M1 *);
    entry void someEntry(M2 *);
  \};
\}
\end{alltt}

and in the \texttt{mod.h} file:

\begin{alltt}
#include "mod.decl.h"
class C : public Chare \{
  public:
    C(M1 *);
    void someEntry(M2 *);
\};
\end{alltt}

Now one can use the class \kw{CProxy}\_\uw{chareType} to create a new instance
of a \index{chare}chare.  Here \uw{chareType} gets replaced with whatever
\index{chare}chare type we want.  For the above example, proxies would be of
type \kw{CProxy}\_\uw{C}. A number of \index{chare}chare creation calls exist
as static or instance methods of class \kw{CProxy}\_\uw{chareType}:

\begin{alltt}
   CProxy_chareType::ckNew(MessageType *msgPtr, CkChareID *vHdl, int destPE);
\end{alltt}

where each parameter above is optional and where

\begin{itemize}

\item \uw{chareType} is the name of the type of \index{chare}chare to be
created.

\item \uw{msgPtr} is a pointer to a \index{message}message whose type must
correspond to the parameter for the \index{constructor}constructor entry method
\uw{chareType}(\uw{MessageType}*) in \index{chare}chare \uw{chareType}.  This
parameter may be omitted if the \index{constructor}constructor takes a void
parameter.

\item \uw{vHdl} is a pointer to a \index{chare}chare handle of type
\kw{CkChareID}, which is filled by the \kw{ckNew} method. This optional
argument can be used if the user desires to have a {\em virtual} handle
\index{virtual handle} to the instance of the \index{chare}chare that will be
created. This handle is useful for sending \index{message}messages to the
\index{chare}chare, even though it has not yet been created on any processor.
Messages sent to this virtual handle are either queued up to be sent to the
\index{chare}chare after it has been created, or simply redirected if the
\index{chare}chare has already been created. For performance reasons,
therefore, virtual handles should be used only when absolutely necessary.
Virtual handles are otherwise like normal \index{handle}handles, and may be
sent to other processors in \index{message}messages.  

\item \uw{destPE}: when a \index{chare}chare is to be created at a specific
processor, the \uw{destPE} is used to specify that processor.  Note that, in
general, for good \index{load balancing}load balancing, the user should let
\charmpp{} determine the processor on which to create a \index{chare}chare.
Under unusual circumstances, however, the user may want to choose the
destination processor.  If a process replicated on every processor is desired,
then a \index{chare group}chare group should be used.  If no particular
processor is required, the parameter can be omitted, or \kw{CK\_PE\_ANY}.

\end{itemize}

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. When a \index{chare}chare is created, it is
initialized by calling its   \index{constructor}constructor \index{entry
method}entry method with the \index{message}message parameter specified to the
\index{chare}chare creation method.  The method operator does not return any
value but fills in the \index{virtual handle}virtual handle to the newly
created \index{chare}chare if specified.

The following are some examples on how to use the \index{chare}chare creation
method to create chares.

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

\begin{alltt}
   MessageType *MsgPtr = new MessageType;
   CProxy_C *pC = new CProxy_C(MsgPtr);
      // or
   MessageType *MsgPtr = new MessageType;
   CProxy_C::ckNew(MsgPtr);
\end{alltt} 

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

\begin{alltt}
   MessageType *MsgPtr = new MessageType;
   CProxy_C::ckNew(MsgPtr, destPE);
\end{alltt}

\item{The following first creates a \kw{CkChareID} \uw{cid},
then creates a new \index{chare}chare of type \uw{C} on processor \uw{destPE}:}

\begin{alltt}
   MessageType *MsgPtr = new MessageType;
   CkChareID cid;
   CProxy_C::ckNew(MsgPtr, \&cid, destPE);
   CProxy_C c(cid);
\end{alltt}

\end{enumerate}

\subsubsection{Method Invocation on Chares}

Before sending a \index{message}message to a \index{chare}chare via an
\index{entry method}entry method, we need to get a \index{proxy}{\it proxy} of
that \index{chare}chare using either the chare identifier, or by creating the
proxy directly from the \index{chare}chare creation (see Section~\ref{chare
creation}. The following code creates a proxy from a \kw{CkChareID}.

\begin{alltt}
   CProxy_chareType chareProxy(chareID);
\end{alltt}

This declares a proxy named \uw{chareProxy} of \uw{chareType} 
using \uw{chareID}.  Alternatively, we can create a proxy pointer:

\begin{alltt}
CProxy_chareType *chareProxyPointer = new CProxy_chareType(chareID);
\end{alltt}

This creates a pointer named \uw{chareProxyPointer} which points to the proxy. 

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

\begin{tabbing}
chareProxy.EntryMethod(MessagePointer)
or,
chareProxyPointer->EntryMethod(MessagePointer)
\end{tabbing}

This sends the message pointed to by \uw{MessagePointer} to the
\index{chare}chare whose proxy/proxy pointer is 
\uw{chareProxy}/\uw{chareProxyPointer} at the \index{entry method}entry method 
\uw{EntryMethod},
which must be a valid entry method of that \index{chare}chare type. This call
is asynchronous and non-blocking; it returns immediately after sending the
message. 
