\section{Programming in \pose{}}

This section details syntax and usage of \pose{} constructs with code samples.

\subsection{\pose{} Modules}

A \pose{} module is similar to a Charm++ module.  It is comprised of
an interface file with suffix {\tt .ci}, a header {\tt .h} file, and
the implementation in {\tt .C} files.  Several posers can be described
in one module, and the module can include regular chares as well.  The
module is translated into \charmpp{} before the simulation can be
compiled.  This translation is performed by a Perl script called {\tt
etrans.pl} which is included with \pose{}.  It generates files
suffixed {\tt \_sim.ci}, {\tt \_sim.h}, and {\tt \_sim.C}.

\subsection{Event Message and Poser Interface Description}

Messages, be they event messages or otherwise, are described in the
{\tt .ci} file exactly the way they are in \charmpp{}. Event messages
cannot make use of \charmpp{}'s parameter marshalling, and thus you
must declare them in the {\tt .h} file.  \charmpp{} {\tt varsize}
event messages are currently not implemented in \pose{}.

All event messages inherit from a \pose{} type {\tt eventMsg} which
includes data for timestamps and miscellaneous \pose{} statistics.

~\\
\noindent{\tt {\bf message} {\it myMessage};}\\

Posers are described similar to chares, with a few exceptions.  First,
the {\tt poser} keyword is used to denote that the class is a \pose{}
simulation object class.  Second, event methods are tagged with the
keyword {\tt event} in square brackets. Finally, three components are
specified which indicate how objects of the poser class are to be
simulated.  The {\it sim} component controls the wrapper class and
event queue used by the object.  The {\it strat} component controls
the synchronization strategy the object should use ({\it i.e.}
adaptive or basic optimistic).  The {\it rep} component specifies the
global state representation, which controls how the global state is
kept accurate depending on the synchronization strategy being used
({\it i.e.} checkpointing or no checkpointing).  Currently, there is
only one wrapper type, {\tt sim}.  This 3-tuple syntax is likely to
become obsolete, replaced simply by synchronization strategy only.
Keeping the global state accurate is largely a function of the
synchronization strategy used.  

~\\
\noindent{\tt {\bf poser} {\it mySim} : {\it sim strat rep} \{\\
\indent {\bf entry} {\it mySim}({\it myMessage} *);\\
\indent {\bf entry} [{\bf event}] void {\it myEventMethod}({\bf eventMsg} *);\\
\indent ...\\
\noindent \};}\\

A typical {\tt .ci} file poser specification might look like this:

~\\
\noindent{\tt poser Worker : sim adapt4 chpt \{\\
\indent entry Worker(WorkerCreationMsg *);\\
\indent entry [event] void doWork(WorkMsg *);\\
\indent ...\\
\noindent \};}\\

Note that the constructors and event methods of a poser must take an
event message as parameter.  If there is no data (and thereby no
message defined) that needs to be passed to the method, then the
parameter should be of type {\tt eventMsg *}.  This ensures that
\pose{} will be able to timestamp the event.

\subsection{Declaring Event Messages and Posers}

Currently, event messages are declared with no reference to what they
might inherit from (unlike in Charm++).  The translator takes care of
this. In addition, they must define {\tt operator=}.

~\\
\noindent{\tt class {\it myMessage} \{\\
\indent  public:\\
\indent   int someData;\\
\indent   {\it myMessage}\& operator=(const {\it myMessage}\& obj) \{\\
\indent\indent     {\bf eventMsg}::operator=(obj);\\
\indent\indent     someData = obj.someData;\\
\indent\indent     return *this;\\
\indent   \}\\
\noindent \};}\\

Similarly, posers do not refer to a base class when they are
declared.  Posers are required to have a void constructor declared
that simply initializes the data to sensible values.  A destructor
must be provided as well.  In addition, a {\tt pup} and {\tt
operator=} must be provided.  The {\tt pup} method should call the
{\tt pup} method of the global state representation class being used.

~\\
\noindent{\tt class {\it mySim} \{\\
\indent int anInt; float aFloat; char aString[20];\\
~public:\\
\indent {\it mySim}();\\
\indent {\it mySim}({\it myMessage} *m);\\
\indent \verb|~|{\it mySim}();\\
\indent void pup(PUP::er \&p);\\
\indent {\it mySim}\& operator=(const {\it mySim}\& obj);\\
\indent void {\it myEventMethod}({\bf eventMsg} *m);\\
\indent void {\it myEventMethod}{\bf \_anti}({\bf eventMsg} *m);\\
\indent void {\it myEventMethod}{\bf \_commit}({\bf eventMsg} *m);\\
\indent ...\\
\noindent \};}\\

Further, for each event method, a commit method should be declared,
and if the synchronization strategy being used is optimistic or
involves any sort of rollback, an anti-method should also be provided.
The syntax of these declarations is shown above.  Their usage and
implementation will be described next.

\subsection{Implementing Posers}

The void constructor for a poser should be defined however the user
sees fit.  It could be given an empty body and should still work for
\pose{}.  Poser entry constructors (those described in the {\tt .ci}
file) should follow the template below:

~\\
\noindent{\tt {\it mySim}::{\it mySim}({\it myMessage} *m)\\
\noindent\{\\
\indent // initializations from $m$\\
\indent ...\\
\indent delete m;\\
\indent ...\\
\noindent \};}\\

Note that while the incoming message $m$ may be deleted here in the
constructor, event messages received on event methods should {\bf not} be
deleted.  The PDES fossil collection will take care of those.

An event method should have the following form:

~\\
\noindent{\tt void {\it mySim}::{\it myEventMethod}(eventMsg *m) \{\\
\indent // body of method \\
\noindent \};}\\

Again, $m$ is never deleted in the body of the event.  A side effect
of optimistic synchronization and rollback is that we would like the
effects of event execution to be dependent only upon the state
encapsulated in the corresponding poser.  Thus, accessing arbitrary
states outside of the simulation, such as by calling {\tt rand}, is
forbidden.  We are planning to fix this problem by adding a {\tt
  POSE\_rand()} operation which will generate a random number the first
time the event is executed, and will checkpoint the number for use in
subsequent re-executions should a rollback occur.

\subsection{Creation of Poser Objects}

Posers are created within a module using the following syntax:

~\\
\noindent {\tt int hdl = 13;  // handle should be unique\\
\noindent {\it myMessage} *m = new {\it myMessage};\\
\noindent m->someData = 34;\\
\noindent {\bf POSE\_create}({\it mySim}(m), hdl, 0);}\\

This creates a {\tt mySim} object that comes into existence at
simulation time zero, and can be referred to by the handle 13.  

Creating a poser from outside the module ({\it i.e.} from {\tt main})
is somewhat more complex:

~\\
\noindent {\tt int hdl = 13;\\
\noindent {\it myMessage} *m = new {\it myMessage};\\
\noindent m->someData = 34;\\
\noindent m->{\bf Timestamp}(0);\\
\noindent (*(CProxy\_{\it mySim} *) \& {\bf POSE\_Objects})[hdl].insert(m);}\\

This is similar to what the module code ultimately gets translated to
and should be replaced by a macro with similar syntax soon.

\subsection{Event Method Invocations}

Event method invocations vary significantly from entry method
invocations in Charm++, and various forms should be used depending on
where the event method is being invoked.  In addition, event messages
sent to an event method should be allocated specifically for an event
invocation, and cannot be recycled or deleted.

There are three ways to send events within a \pose{} module.  The first
and most commonly used way involves specifying and offset in
simulation time from the current time.  The syntax follows:

~\\
\noindent {\tt aMsg = new {\bf eventMsg};\\
\noindent {\bf POSE\_invoke}({\it myEventMethod}(aMsg), {\it
mySim}, hdl, 0);}\\

Here, we've created an {\tt eventMsg} and sent it to {\tt
myEventMethod}, an event entry point on {\tt mySim}.  {\tt mySim} was
created at handle {\tt hdl}, and we want the event to take place now,
i.e. at the current simulation time, so the offset is zero.  

The second way to send an event is reserved for use by non-poser
objects within the module.  It should not be used by posers.  This
version allows you to specify an absolute simulation time at which the
event happens (as opposed to an offset to the current time).  Since
non-poser objects are not a part of the simulation, they do not have a
current time, or OVT, by which to specify an offset.  The syntax is
nearly identical to that above, only the last parameter is an absolute
time.

~\\
\noindent {\tt aMsg = new {\bf eventMsg};\\
\noindent {\bf POSE\_invoke\_at}({\it myEventMethod}(aMsg), {\it
mySim}, hdl, 56);}\\

Posers should not use this approach because of the risk of specifying
an absolute time that is earlier than the current time on the object
sending the event.  

Using this method, event methods can be injected into the system from
outside any module, but this is not recommended.

The third approach is useful when an object send events to itself.  It
is simply a slightly shorter syntax for the same thing as {\tt
POSE\_invoke}: 

~\\
\noindent {\tt aMsg = new {\bf eventMsg};\\
\noindent {\bf POSE\_local\_invoke}({\it myEventMethod}(aMsg), offset);}\\

\subsection{Elapsing Simulation Time}

We've seen in the previous section how it is possible to advance
simulation time by generating events with non-zero offsets of current
time.  When such events are received on an object, if the object is
behind, it advances its local simulation time (object virtual time or
OVT) to the timestamp of the event.

It is also possible to elapse time on an object while the object is
executing an event.  This is accomplished thus:

~\\
\noindent {\tt {\bf elapse}(42);}\\

The example above would simulate the passage of forty-two time units
by adding as much to the object's current OVT.

\subsection{Interacting with a \pose{} Module and the \pose{} System}

\pose{} modules consist of {\tt <$modname$>.ci}, {\tt <$modname$>.h}
and {\tt <$modname$>.C} files that are translated via {\tt etrans.pl}
into {\tt <$modname$>\_sim.ci}, {\tt <$modname$>\_sim.h} and {\tt
<$modname$>\_sim.C} files.  To interface these with a main program
module, say $Pgm$ in files {\tt pgm.ci}, {\tt pgm.h} and {\tt pgm.C},
the {\tt pgm.ci} file must declare the \pose{} module as extern in the
{\tt mainmodule Pgm} block. For example:

~\\
\noindent{\tt mainmodule Pgm \{\\
\indent  extern module <$modname$>;\\
\indent  readonly CkChareID mainhandle;\\
   \\
\indent  mainchare main \{\\
\indent\indent    entry main();\\
\indent  \};\\
\noindent \};}\\

The {\tt pgm.C} file should include {\tt pose.h} and {\tt<$modname$>\_sim.h}
along with its own headers, declarations and whatever else it needs.

Somewhere in the {\tt main} function, {\tt POSE\_init()} should be
called.  This initializes all of \pose{}'s internal data structures.
The parameters to {\tt POSE\_init()} specify a termination method.  \pose{} programs can
be terminated in two ways: with inactivity detection or with an end
time.  Inactivity detection terminates after a few iterations of the
GVT if no events are being executed and virtual time is
not advancing.  When an end time is specified, and the GVT passes it,
the simulation exits. If no parameters are provided to {\tt POSE\_init()}, then the 
simulation will use inactivity detection. If a time is provided as the parameter, this time
will be used as the end time.


Now \pose{} is ready for posers.  All posers can be created at this
point, each with a unique handle.  The programmer is responsible for
choosing and keeping track of the handles created for posers.  Once
all posers are created, the simulation can be started:

~\\
\noindent{\tt POSE\_start();}\\
