\subsection{\charmpp{} Messages}

\subsubsection{What are messages?}

A bundle of data sent, via a proxy, to another chare. A message is
a special kind of heap-allocated C++ object.

\subsubsection{Should I use messages?}

It depends on the application. We've found parameter marshalling to be less
confusing and error-prone than messages for small parameters. Nevertheless,
messages can be more efficient, especially if you need to buffer incoming data,
or send complicated data structures (like a portion of a tree).

\subsubsection{What is the best way to pass pointers in a message?}

You can't pass pointers across processors. This is a basic fact of
life on distributed-memory machines.

You can, of course, pass a copy of an object referenced via a pointer
across processors--either dereference the pointer before sending, or use
a varsize message.

\subsubsection{Can I allocate a message on the stack?}

No. You must allocate messages with {\em new}.

\subsubsection{Do I need to delete messages that are sent to me?}

Yes, or you will leak memory! If you receive a message, you are responsible
for deleting it. This is exactly opposite of parameter marshalling,
and much common practice. The only exception are entry methods declared as
[nokeep]; for these the system will free the message automatically at the end of
the method.

\subsubsection{Do I need to delete messages that I allocate and send?}

No, this will certainly corrupt both the message and the heap! Once
you've sent a message, it's not yours any more. This is again exactly the
opposite of parameter marshalling.

\subsubsection{What can a variable-length message contain?}

Variable-length messages can contain arrays of any type, both primitive type or
any user-defined type. The only restriction is that they have to be 1D arrays.

\subsubsection{Do I need to delete the arrays in variable-length messages?}

No, this will certainly corrupt the heap! These arrays are allocated in a single
contiguous buffer together with the message itself, and is deleted when the
message is deleted.

\subsubsection{What are priorities?}

Priorities are special values that can be associated with messages, so that the
Charm++ scheduler will generally prefer higher priority messages when choosing a buffered message from the queue to invoke as an entry method.  Priorities are often respected by Charm++ scheduler, but for correctness, a program must never rely upon any particular ordering of message deliveries. Messages with priorities are typically used to encourage high performance behavior of an application.


For integer priorities, the smaller the priority value, the higher the priority
of the message. Negative value are therefore higher priority than positive ones. 
To enable and set a message's priority there is a special {\em new} syntax and
{\em CkPriorityPtr} function; see the manual for details. If no priority is set,
messages have a default priority of zero.

\subsubsection{Can messages have multiple inheritance in Charm++?}

Yes, but you probably shouldn't.  Perhaps you want to consider using \htmladdnormallink{generic or meta programming}{http://charm.cs.illinois.edu/manuals/html/charm++/15.html} techniques with templated chares, methods, and/or messages instead. 

%<br>Messages can't be inherited at all-- they don't even have *single*
%inheritance. This is a silly limitation; but the fact that messages need
%to be transmitted as flat byte streams puts strong limits on what we can
%do with them.

%\subsubsection{What is the difference between {\tt new} and {\tt alloc}?}


%My understanding is that </b><tt>new</tt><b>
%calls </b><tt>alloc</tt><b>, but what else is
%</b><tt>new</tt><b> doing?
%I.e. why do both exist?</b></li>

%<br><tt>new</tt> is an operator for the class, and
%<tt>alloc</tt> is a
%static method. <tt>alloc</tt> basically calls <tt>CkAlloc</tt> after calculating
%the sizes and the priority bits etc. <tt>new</tt> is just a wrapper around
%<tt>alloc</tt>.
%You should always call <tt>new</tt>.

