* deleting a couple of files not in use (integrated into other files)
authorFilippo Gioachin <gioachin@illinois.edu>
Fri, 21 Dec 2007 19:25:00 +0000 (19:25 +0000)
committerFilippo Gioachin <gioachin@illinois.edu>
Fri, 21 Dec 2007 19:25:00 +0000 (19:25 +0000)
* changing all textrm to texttt (typewriter formatting)
* added faq in the charm general programming section about program startup

13 files changed:
doc/faq/Makefile
doc/faq/arrays.tex
doc/faq/charm.tex
doc/faq/debugging.tex
doc/faq/general.tex [deleted file]
doc/faq/groups.tex
doc/faq/install.tex
doc/faq/internals.tex
doc/faq/messages.tex
doc/faq/nodegroups.tex [deleted file]
doc/faq/other.tex
doc/faq/ports.tex
doc/faq/pup.tex

index 7b6eae481c4c939df93656eb6092437d65b15e23..6b6d8b26e52de97247ccedd14a10f10ba3d74016 100644 (file)
@@ -1,6 +1,6 @@
 # Stub makefile for LaTeX PPL manual
 FILE=manual
-TEX=$(FILE).tex overview.tex general.tex charm.tex arrays.tex groups.tex messages.tex \
+TEX=$(FILE).tex overview.tex charm.tex arrays.tex groups.tex messages.tex \
        other.tex install.tex debugging.tex ports.tex converse.tex internals.tex pup.tex
 DEST=faq
 LATEX2HTML=$(L2H) -split 2
index b811aa292ab3d1835be75f212c8975ce31b6370e..e4ee1bc29e5d1bc3ce33599c979fc9a1d54d568d 100644 (file)
@@ -2,7 +2,7 @@
 
 \subsubsection{How do I know which processor a chare array element is running on?}
 
-At any given instant, you can call \textrm{CkMyPe()} to find out where
+At any given instant, you can call {\tt CkMyPe()} to find out where
 you are. There is no reliable way to tell where another array element is;
 even if you could find out at some instant, the element might immediately
 migrate somewhere else!
@@ -45,7 +45,7 @@ with the {\em +balancer} option, or at runtime with the {\em -balancer} option.
 
 \subsubsection{What is the migration constructor and why do I need it?}
 
-The migration constructor (a constructor that takes \textrm{CkMigrateMessage *}
+The migration constructor (a constructor that takes {\tt CkMigrateMessage *}
 as parameter) is invoked when an array element migrates to a new
 processor. If there is anything you want to do when you migrate, you could put
 it here. However, even if you don't want to do anything, you must create it, as
@@ -60,7 +60,7 @@ that it can be created, and these must be declared in the {\em .ci} file.
 \subsubsection{What happens to the old copy of an array element after it migrates?}
 
 After sizing and packing a migrating array element, the array manager
-\textrm{delete}s
+{\tt delete}s
 the old copy. As long as all the array element destructors in the non-leaf
 nodes of your inheritance hierarchy are {\em virtual destructors}, with
 declaration syntax:
@@ -88,14 +88,14 @@ at the next {\em AtSync()}?}
 %<br>No.
 
 
-\subsubsection{When not using \textrm{AtSync} for LB, when does the LB start
+\subsubsection{When not using {\tt AtSync} for LB, when does the LB start
 up? Where is the code that periodically checks if load balancing can be
 done?}
 
-If not using \textrm{usesAtSync}, the load balancer can start up at
-anytime. There is a dummy \textrm{AtSync} for each array element which
+If not using {\tt usesAtSync}, the load balancer can start up at
+anytime. There is a dummy {\tt AtSync} for each array element which
 by default tells the load balancer that it is always ready. The LDBD manager
-has a syncer (\textrm{LBDB::batsyncer}) which periodically calls \textrm{AtSync}
+has a syncer ({\tt LBDB::batsyncer}) which periodically calls {\tt AtSync}
 roughly every 1ms to trigger the load balancing (this timeout can be changed
 with the {\em +LBPeriod} option). In this load balancing
 mode, users have to make sure all migratable objects are always ready to
index 95903e8c8419d3ca3bf3aa7b8d02ad5d12bee00d..23375d4a883f227970208b0fc377dbd43e63177a 100644 (file)
@@ -46,7 +46,7 @@ to wait for foo.
 
 \subsubsection{Can I make a method synchronous? Can I then return a value?}
 
-Yes. If you want synchronous methods, so the caller will block, use the \textrm{[sync]}
+Yes. If you want synchronous methods, so the caller will block, use the {\tt [sync]}
 keyword before the method in the .ci file. This requires the sender to be a threaded
 entry method, as it will be suspended until the callee finishes.
 Sync entry methods are allowed to return values to the caller.
@@ -111,7 +111,7 @@ void A::hereIsTheData(myclass_t data) \{
 Now {\em b} can be called from several different places in {\em a},
 or from several different modules.
 
-\subsubsection{Why should I prefer the callback way to return data rather than using \textrm{[sync]} entry methods?}
+\subsubsection{Why should I prefer the callback way to return data rather than using {\tt [sync]} entry methods?}
 
 There are a few reasons for that:
 
@@ -129,7 +129,7 @@ can be called. This allows for potential problems if the suspending method does
 leave some objects in an inconsistent state.
 
 \item
-Finally, and probably most important, \textrm{[sync]} entry methods can only be
+Finally, and probably most important, {\tt [sync]} entry methods can only be
 used to return a value that can be computed by a single chare. When more
 flexibility is needed, such in cases where the resulting value needs to the
 contribution of multiple objects, the callback methodology is the only one
@@ -138,6 +138,38 @@ will use a reduction to collect back the results after they have been computed.
 
 \end{itemize}
 
+\subsubsection{How does the initializazion in Charm work?}
+
+Each processor executes the following operations strictly in order:
+\begin{enumerate}
+\item All methods registered as {\em initnode};
+\item All methods registered as {\em initproc};
+\item On processor zero, all {\em mainchares} constructor method is invoked (the ones taking a {\tt CkArgMsg*});
+\item The read-onlies are propagated from processor zero to all other processors;
+\item The nodegroups are created;
+\item The groups are created. During this phase, for all the chare arrays have been created with a block allocation, the corresponding array elements are instantiated;
+\item Initialization terminated and all messages are available for processing, including the messages responsible for the instantiation of array elements manually inserted.
+\end{enumerate}
+
+This implies that you can assume that the previous steps has completely finished
+before the next one starts, and any side effect from all the previous steps are
+committed (and can therefore be used).
+
+Inside a single step there is no order guarantee. This implies that, for example,
+two groups allocated from mainchare can be instantiated in any order. The only
+exception to this is processor zero, where chare objects are instantiated
+immediately when allocated in the mainchare, i.e if two groups are allocated,
+their order is fixed by the allocation order in the mainchare constructing them. 
+Again, this is only valid for processor zero, and in no other processor this
+assumption should be made.
+
+To notice that if array elements are allocated in block (by specifying the
+number of elements at the end of the {\tt ckNew} function), they are all
+instantiated before normal execution is resumed; if manual insertion is used,
+each element can be constructed at any time on its home processor, and not
+necessarily before other regular communication messages have been delivered to
+other chares (including other array elements part of the same array).
+
 \subsubsection{Does Charm++ support C and Fortran?}
 
 %Not directly, although most of the <a href="/research/">frameworks</a>
@@ -178,7 +210,7 @@ You'll get a runtime error ``proxy has not been initialized'' if you try
 to use an uninitialized proxy.
 \end{itemize}
 
-\subsubsection{What is wrong if I do \textrm{A *ap = new CProxy\_A(handle)}?}
+\subsubsection{What is wrong if I do {\tt A *ap = new CProxy\_A(handle)}?}
 
 This will not compile, because a {\em CProxy\_A} is not an {\em A}.
 What you want is {\em CProxy\_A *ap = new CProxy\_A(handle)}.
@@ -247,13 +279,13 @@ You then refer to the variable in your program as {\em someChare::someGroup}.
 
 \subsubsection{How do I measure the time taken by a program or operation?}
 
-You can use \textrm{CkWallTimer()} to determine the time on some particular
+You can use {\tt CkWallTimer()} to determine the time on some particular
 processor. To time some parallel computation, you need to call CkWallTimer
 on some processor, do the parallel computation, then call CkWallTimer again
 on the same processor and subtract.
 
-\subsubsection{What do \textrm{CmiAssert} and
-\textrm{CkAssert} do?}
+\subsubsection{What do {\tt CmiAssert} and
+{\tt CkAssert} do?}
 
 These are just like the standard C++ {\em assert} calls in {\em <assert.h>}--
 they call abort if the condition passed to them is false.
index 1b7717484b3d2502beec062d5990c79388aa828e..a9c20da474f11e728b0190faf84f06a64a80117e 100644 (file)
@@ -6,7 +6,7 @@ There are many ways to debug programs written in Charm++:
 
 \begin{description}
 
-\item[print] By using \textrm{CkPrintf}, values from critical point in the program can be
+\item[print] By using {\tt CkPrintf}, values from critical point in the program can be
 printed.
 
 \item[gdb] This can be used both on a single processor, and in parallel
@@ -23,7 +23,7 @@ attached to specific processors on demand.
 \subsubsection{How do I use charmdebug?}
 
 Currently charmdebug is tested to work only under net- versions. With other versions,
-testing is pending. The executable is present in \textrm{java/bin/charmdebug} of
+testing is pending. The executable is present in {\tt java/bin/charmdebug} of
 the Charm++ distribution. To start, simply substitute ``charmdebug'' to
 ``charmrun'':
 \begin{alltt}shell> <path>/charmdebug ./myprogram\end{alltt}
@@ -60,13 +60,13 @@ shell> ./charmrun ./myprogram +p2 ++debug
 %<br><tt>...</tt>
 %<br><tt>&nbsp; > dbx -p 34554234</tt>
 
-\subsubsection{When I try to use the {\em ++debug} option I get: \textrm{remote
+\subsubsection{When I try to use the {\em ++debug} option I get: {\tt remote
 host not responding... connection closed}}
 
 First, make sure the program at least starts to run properly without {\em ++debug}
 (i.e. charmrun is working and there are no problems with the program startup
 phase). You need to make sure that gdb or dbx, and xterm are installed
-on all the machines you are using (not the one that is running \textrm{charmrun}).
+on all the machines you are using (not the one that is running {\tt charmrun}).
 If you are working on remote machines from Linux, you need to run ``xhost +''
 locally to give the remote machines permission to display an xterm on
 your desktop. If you are working from a Windows machine, you need an X-win
@@ -128,7 +128,7 @@ least happen in causal order. Note that this does dramatically slow down
 output.
 
 \subsubsection{Is there a way to flush the print buffers in Charm++ (like
-\textrm{fflush()})?}
+{\tt fflush()})?}
 
 Charm++ automatically flushes the print buffers every newline and at
 program exit. There is no way to manually flush the buffers at another
@@ -163,7 +163,7 @@ from uninitialized data, corrupting the heap, etc. The solution is to never,
 ever send pointers in messages -- you need to send the data the pointer points
 to, not the pointer.
 
-\subsubsection{I get the error: ``\textrm{Group ID is zero-{}- invalid!}''. What does
+\subsubsection{I get the error: ``{\tt Group ID is zero-{}- invalid!}''. What does
 this mean?}
 
 The {\em group} it is refering to is the chare group. This
@@ -171,7 +171,7 @@ error is often due to using an uninitialized proxy or handle; but it's
 possible this indicates severe corruption. Run with {\em ++debug} and check
 it you just sent a message via an uninitialized proxy.
 
-\subsubsection{I get the error: \textrm{Null-Method Called. Program may have Unregistered
+\subsubsection{I get the error: {\tt Null-Method Called. Program may have Unregistered
 Module!!} What does this mean?}
 
 You are trying to use code from a module that has not been properly
@@ -193,16 +193,16 @@ Charmrun: error on request socket-{}-
 Socket closed before recv.
 \end{alltt}
 
-This means that the node program died without informing \textrm{charmrun}
+This means that the node program died without informing {\tt charmrun}
 about it, which typically means a segmentation fault while in the interrupt
 handler or other critical communications code. This indicates severe
 corruption in Charm++'s data structures, which is likely the result of
 a heap corruption bug in your program. Re-linking with {\em -memory paranoid}
 may clarify the true problem.
 
-\subsubsection{When I run my program, sometimes I get a \textrm{Hangup}, and
-sometimes \textrm{Bus Error}. What do these messages indicate?}
+\subsubsection{When I run my program, sometimes I get a {\tt Hangup}, and
+sometimes {\tt Bus Error}. What do these messages indicate?}
 
-\textrm{Bus Error} and \textrm{Hangup} both are indications that your
+{\tt Bus Error} and {\tt Hangup} both are indications that your
 program is terminating abnormally, i.e. with an uncaught signal (SEGV or
 SIGBUS). You should definitely run the program with gdb, or use {\em ++debug}.
diff --git a/doc/faq/general.tex b/doc/faq/general.tex
deleted file mode 100644 (file)
index a3268b5..0000000
+++ /dev/null
@@ -1,2 +0,0 @@
-\subsection{General \charmpp{} Questions}
-
index 236c6bb290bc6cf53ead3797be6c9fa15f1bf4e2..e68e780c837fa8ffcd93f705f9796b14eeab50a7 100644 (file)
@@ -39,7 +39,7 @@ the .ci file. They {\em cannot} migrate from one processor to another during
 normal execution, but only to disk for checkpointing purposes.
 
 Migratable groups must declare a migration constructor (taking
-\textrm{CkMigrateMessage *} as a parameter) and a pup routine. The migration
+{\tt CkMigrateMessage *} as a parameter) and a pup routine. The migration
 construtor {\em must} call the superclass migration constructor as in this
 example:
 \begin{alltt}
index 907f83ae05ef15f42a7e594ccd727f0503eda926..7ffbf1a3cea438eae6de62af017b0bff76761029 100644 (file)
@@ -12,13 +12,13 @@ will likely contain bug fixes not found in the releases.
 
 \subsubsection{How do I compile Charm++?}
 
-Run the interactive build script \textrm{./build} with no extra arguments If this fails,
+Run the interactive build script {\tt ./build} with no extra arguments If this fails,
 email \htmladdnormallink{ppl@cs.uiuc.edu}{mailto:ppl@cs.uiuc.edu} with the
 problem. Include the build line used (this is saved automatically in
-\textrm{smart-build.log})
+{\tt smart-build.log})
 
 If you have a very unusual machine configuration, you will have to run
-\textrm{./build\ --help} to list all possible build options. You will then choose the closest
+{\tt ./build\ --help} to list all possible build options. You will then choose the closest
 architecture, and then you may have to modify the associated conf-mach.sh and
 conv-mach.h files in src/arch to point to your desired compilers and options. If
 you develop a significantly different platform, send the modified files to
@@ -27,7 +27,7 @@ in the distribution.
 
 \subsubsection{How do I compile AMPI?}
 
-Run the interactive build script \textrm{./build} and choose the option for building
+Run the interactive build script {\tt ./build} and choose the option for building
 ``Charm++, AMPI, ParFUM, FEM and other libraries''.
 
 \subsubsection{Can I remove part of charm tree after compilation to free disk space?}
@@ -248,11 +248,11 @@ machines as for normal MPI applications.
 
 \subsubsection{How do I use {\em ssh} instead of the deprecated {\em rsh}?}
 
-You need to set up your \textrm{.ssh/authorized\_keys} file
+You need to set up your {\tt .ssh/authorized\_keys} file
 correctly. Setup no-password logins using ssh by putting the correct host
-key (ssh-keygen) in the file \textrm{.ssh/authorized\_keys}.
+key (ssh-keygen) in the file {\tt .ssh/authorized\_keys}.
 
-Finally, in the \textrm{.nodelist} file,
+Finally, in the {\tt .nodelist} file,
 you specify the shell to use for remote execution of a program using
 the keyword {\em ++shell}.
 \begin{alltt}
index 2cb1294a625d53dfddcd21c08da42d389e443b49..e29821127f8a6bddd70d76c880d4d3e661c9cb82 100644 (file)
@@ -3,14 +3,14 @@
 \subsubsection{How is the Charm++ source code organized and built?}
 
 All the Charm++ core source code is soft-linked into the
-\textrm{charm/<archname>/tmp}
+{\tt charm/<archname>/tmp}
 directory when you run the build script. The libraries and frameworks are
-under \textrm{charm/<archname>/tmp/libs}, in either \textrm{ck-libs} or
-\textrm{conv-libs}.
+under {\tt charm/<archname>/tmp/libs}, in either {\tt ck-libs} or
+{\tt conv-libs}.
 
 \subsubsection{I just changed the Charm++ core. How do I recompile Charm++?}
 
-cd into the \textrm{charm/<archname>/tmp} directory and make. If you want to
+cd into the {\tt charm/<archname>/tmp} directory and make. If you want to
 compile only a subset of the entire set of libraries, you can specify it to
 make. For example, to compile only the Charm++ RTS, type {\em make charm++}.
 
index 5188c675fe16719b3a17ff24ad9187875193004d..a2276fc3d90cbf119ea1d32cc9c19891e8b25814 100644 (file)
@@ -75,7 +75,7 @@ messages have a default priority of zero.
 %to be transmitted as flat byte streams puts strong limits on what we can
 %do with them.
 
-\subsubsection{What is the difference between \textrm{new} and \textrm{alloc}?}
+\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
diff --git a/doc/faq/nodegroups.tex b/doc/faq/nodegroups.tex
deleted file mode 100644 (file)
index f37b301..0000000
+++ /dev/null
@@ -1,2 +0,0 @@
-\subsection{\charmpp{} Nodegroups}
-
index 320780578c8948505d57b1c6d894d77576057c5d..9cd2ffeb29b7e657b80a9ab8663ca109c2c9b9c1 100644 (file)
@@ -7,7 +7,7 @@ control dependencies in message-driven programs. It combines the efficiency
 of message-driven execution with the explicitness of control specification.
 Structured Dagger allows easy expression of dependencies among messages
 and computations and also among computations within the same object using
-\textrm{when-blocks}
+{\tt when-blocks}
 and various structured constructs. See the Charm++ manual for the details.
 
 \subsubsection{What are the performance problems with AMPI packing and unpacking?}
@@ -27,7 +27,7 @@ of a Charm++ message) while sending.
 %with collective operations can be done this way, so I have changed AMPI
 %to be a standalone Charm++ library, rather than being dependent on Tempo.
 
-\subsubsection{Is \textrm{TempoArray::ckTempoSendElem()} the only way for non-AMPI
+\subsubsection{Is {\tt TempoArray::ckTempoSendElem()} the only way for non-AMPI
 code to communicate with running AMPI code?}
 
 %<br>A static method <tt>sendraw</tt> is added to the AMPI class, that allows
index bf5bd2ab7659d1865b8f3c43e1a34d6f8449d851..9c755f4b05151f3a559dfb2c5cff72f596b45009 100644 (file)
@@ -24,7 +24,7 @@ ourselves?}
 
 The source is always available, and you're welcome to make it run anywhere.
 Any kind of UNIX, Windows, and MacOS machine should be straightforward: just a
-few modifications to \textrm{charm/src/arch/.../conv-mach.h} (for compiler
+few modifications to {\tt charm/src/arch/.../conv-mach.h} (for compiler
 issues) and possibly
 a new {\em machine.c} (if there's a new communication system involved).
 However, porting to a Lisp machine or VAX would be fairly difficult.
index b755107f069317af7db2e71355298daea42a5698..dff71b7dded0d2cd169e5aaecbb8ab80893e3ee7 100644 (file)
@@ -56,36 +56,36 @@ class foo \{
 \end{alltt}
 
 \subsubsection{When using automatic allocation via PUP::able, what do these calls mean?
-\textrm{PUPable\_def(parent); PUPable\_def(child);}}
+{\tt PUPable\_def(parent); PUPable\_def(child);}}
 
 For the automatic allocation described in {\em Automatic allocation via
-\textrm{PUP::able}} of the manual, each class needs four things:
+{\tt PUP::able}} of the manual, each class needs four things:
 \begin{itemize}
 \item A migration constructor
 
 \item
-\textrm{PUPable\_decl(className)} in the class declaration in the {\em .h}
+{\tt PUPable\_decl(className)} in the class declaration in the {\em .h}
 file
 
 \item
-\textrm{PUPable\_def(className)} at file scope in the {\em .C} file
+{\tt PUPable\_def(className)} at file scope in the {\em .C} file
 
 \item
-\textrm{PUPable\_reg(className)} called exactly once on every node. You
+{\tt PUPable\_reg(className)} called exactly once on every node. You
 typically use the {\em initproc} mechanism to call these.
 \end{itemize}
-See \textrm{charm/tests/charm++/megatest/marshall.[hC]} for an executable
+See {\tt charm/tests/charm++/megatest/marshall.[hC]} for an executable
 example.
 
-\subsubsection{What is the difference between \textrm{p|data;} and
-\textrm{p(data);}? Which one should I use?}
+\subsubsection{What is the difference between {\tt p|data;} and
+{\tt p(data);}? Which one should I use?}
 
 For most system- and user-defined structure {\em someHandle}, you want
-\textrm{p|someHandle;} instead of \textrm{p(someHandle);}
+{\tt p|someHandle;} instead of {\tt p(someHandle);}
 
 The reason for the two incompatible syntax varieties is that the bar
-operator can be overloaded {\em outside} \textrm{pup.h} (just like the
-\textrm{std::ostream}'s \textrm{operator{<}<});
+operator can be overloaded {\em outside} {\tt pup.h} (just like the
+{\tt std::ostream}'s {\tt operator{<}<});
 while the parenthesis operator can take multiple arguments (which is needed
 for efficiently PUPing arrays).