File: proc_lib.html

package info (click to toggle)
erlang-doc-html 1%3A8.0-1
links: PTS
area: main
in suites: woody
size: 18,028 kB
ctags: 7,419
sloc: perl: 1,841; ansic: 323; erlang: 155
file content (216 lines) | stat: -rw-r--r-- 9,856 bytes
<HTML>
<HEAD>
<!-- refpage -->
<TITLE>proc_lib</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<CENTER>


<A HREF="http://www.erlang.se"><IMG BORDER=0 ALT="[Erlang Systems]" SRC="min_head.gif"></A>
<H1>proc_lib</H1>
</CENTER>
<H3>MODULE</H3>
<UL>
proc_lib</UL>
<H3>MODULE SUMMARY</H3>
<UL>
Plug-in Replacements for spawn/3,4 and spawn_link/3,4.</UL>
<H3>DESCRIPTION</H3>
<UL>
<P>The <CODE>proc_lib</CODE> module is used to initialize some useful
information when a process starts. The registered names, or the
process identities, of the <CODE>parent</CODE> process, and the parent ancestors, 
are stored together with information about the function initially called 
in the process.

<P>A crash report is generated if the process terminates with a reason other than <CODE>normal</CODE>
or <CODE>shutdown</CODE>. <CODE>shutdown</CODE> is used to terminate an abnormal process in a controlled manner. A crash report contains the previously stored information such as ancestors and initial function, the termination reason, and information regarding other processes which terminate as a result of this process terminating.<P>The crash report is sent to the <CODE>error_logger</CODE>. An event handler has to be installed in the <CODE>error_logger</CODE> event manager in order to handle these reports. The crash report is tagged <CODE>crash_report</CODE> and the <CODE>format/1</CODE> function should be called
in order to format the report.
</UL>
<H3>EXPORTS</H3>
<P><A NAME="spawn%3"><STRONG><CODE>spawn(Module,Func,Args) -&#62; Pid</CODE></STRONG></A><BR>
<A NAME="spawn%4"><STRONG><CODE>spawn(Node,Module,Func,Args) -&#62; Pid</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Func = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = [Arg]</CODE></STRONG><BR>
<STRONG><CODE>Arg = term()</CODE></STRONG><BR>
<STRONG><CODE>Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Spawns a new process and initializes it as described above.
        The process is spawned using the <CODE>spawn</CODE> BIF.
        The process can be spawned on another <CODE>Node</CODE>.        
</UL>
<P><A NAME="spawn_link%3"><STRONG><CODE>spawn_link(Module,Func,Args) -&#62; Pid</CODE></STRONG></A><BR>
<A NAME="spawn_link%4"><STRONG><CODE>spawn_link(Node,Module,Func,Args) -&#62; Pid</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Func = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = [Arg]</CODE></STRONG><BR>
<STRONG><CODE>Arg = term()</CODE></STRONG><BR>
<STRONG><CODE>Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Spawns a new process and initializes it as described above.
        The process is spawned using the <CODE>spawn_link</CODE> BIF.
        The process can be spawned on another <CODE>Node</CODE>.        
</UL>
<P><A NAME="start%3"><STRONG><CODE>start(Module,Func,Args) -&#62; Ret</CODE></STRONG></A><BR>
<A NAME="start%4"><STRONG><CODE>start(Module,Func,Args,Time) -&#62; Ret</CODE></STRONG></A><BR>
<A NAME="start_link%3"><STRONG><CODE>start_link(Module,Func,Args) -&#62; Ret</CODE></STRONG></A><BR>
<A NAME="start_link%4"><STRONG><CODE>start_link(Module,Func,Args,Time) -&#62; Ret</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Func = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = [Arg]</CODE></STRONG><BR>
<STRONG><CODE>Arg = term()</CODE></STRONG><BR>
<STRONG><CODE>Time = integer &#62;= 0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Ret = term() | {error, Reason}</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Starts a new process synchronously. Spawns the process
         using <CODE>proc_lib:spawn/3</CODE> or
         <CODE>proc_lib:spawn_link/3</CODE>, and waits for the process to
         start. When the process has started, it <STRONG>must</STRONG> call
         <CODE>proc_lib:init_ack(Parent, Ret)</CODE> or
         <CODE>proc_lib:init_ack(Ret)</CODE>, where <CODE>Parent</CODE>
         is the process that evaluates <CODE>start</CODE>. At this time,
         <CODE>Ret</CODE> is returned from <CODE>start</CODE>.

         <P>If the <CODE>start_link</CODE> function is used and the
         process crashes before <CODE>proc_lib:init_ack</CODE> is called,
         <CODE>{error, Reason}</CODE> is returned if the calling process
         traps exits.

         <P>If <CODE>Time</CODE> is specified as an integer, this function
         waits for <CODE>Time</CODE> milliseconds for the process to start
         (<CODE>proc_lib:init_ack</CODE>). If it has not
         started within this time, <CODE>{error, timeout}</CODE> is
         returned, and the process is killed.
</UL>
<P><A NAME="init_ack%2"><STRONG><CODE>init_ack(Parent, Ret) -&#62; void()</CODE></STRONG></A><BR>
<A NAME="init_ack%1"><STRONG><CODE>init_ack(Ret) -&#62; void()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>Parent = pid()</CODE></STRONG><BR>
<STRONG><CODE>Ret = term()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>This function is used by a process that has been started by a
        <CODE>proc_lib:start</CODE> function. It tells
        <CODE>Parent</CODE> that the process has initialized itself, has
        started, or has failed to initialize itself. The <CODE>init_ack/1</CODE>
        function uses the parent value previously stored by the
        <CODE>proc_lib:start</CODE> function. If the <CODE>init_ack</CODE> function
        is not called (e.g. if the init function crashes) and
        <CODE>proc_lib:start/3</CODE> is used, that function never returns
        and the parent hangs forever. This can be avoided by using a
        time out in the call to <CODE>start</CODE>, or by using
        <CODE>start_link</CODE>.

        <P>The following example illustrates how this function and
        <CODE>proc_lib:start_link</CODE> are used.
        <PRE>-module(my_proc).
-export([start_link/0]).
start_link() -&#62;
    proc_lib:start_link(my_proc, init, [self()]).
init(Parent) -&#62;
    case do_initialization() of
        ok -&#62;
            proc_lib:init_ack(Parent, {ok, self()});
        {error, Reason} -&#62;
            exit(Reason)
    end,
    loop().
loop() -&#62;
    receive
        ....
        </PRE></UL>
<P><A NAME="format%1"><STRONG><CODE>format(CrashReport) -&#62; string()</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>CrashReport = void()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Formats a previously generated crash report. The formatted
report is returned as a string.
</UL>
<P><A NAME="initial_call%1"><STRONG><CODE>initial_call(PidOrPinfo) -&#62; {Module,Function,Args} | false</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>PidOrPinfo = pid() | {X,Y,Z} | ProcInfo</CODE></STRONG><BR>
<STRONG><CODE>X = Y = Z = int()</CODE></STRONG><BR>
<STRONG><CODE>ProcInfo = [void()]</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = [term()]</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Extracts the initial call of a process that was spawned using the
        spawn functions described above. <CODE>PidOrPinfo</CODE> can either be a Pid,
        an integer tuple (from which a pid can be created), or the
        process information of a process (fetched through a
        <CODE>erlang:process_info/1</CODE> function call).
</UL>
<P><A NAME="translate_initial_call%1"><STRONG><CODE>translate_initial_call(PidOrPinfo) -&#62; {Module,Function,Arity}</CODE></STRONG></A><BR>
<P><UL>Types:
<UL>
<STRONG><CODE>PidOrPinfo = pid() | {X,Y,Z} | ProcInfo</CODE></STRONG><BR>
<STRONG><CODE>X = Y = Z = int()</CODE></STRONG><BR>
<STRONG><CODE>ProcInfo = [void()]</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arity = int()</CODE></STRONG><BR>
</UL>
</UL>
<UL>
<P>Extracts the initial call of a process which was spawned using the
        spawn functions described above. If the initial call is to one of the system
        defined behaviours such as <CODE>gen_server</CODE> or <CODE>gen_event</CODE>, it is translated
        to more useful information. If a <CODE>gen_server</CODE> is spawned,
        the returned <CODE>Module</CODE> is the name of the callback module and
        <CODE>Function</CODE> is <CODE>init</CODE> (the function that initiates the
        new server).<P>A <CODE>supervisor</CODE> and a <CODE>supervisor_bridge</CODE> are also <CODE>gen_server</CODE> processes.
In order to return information that this process is a supervisor and the name of the call-back module, <CODE>Module</CODE> is <CODE>supervisor</CODE> and <CODE>Function</CODE> is
the name of the supervisor callback module. <CODE>Arity</CODE> is <CODE>1</CODE>
since the <CODE>init/1</CODE> function is called initially in the callback module.<P>By default, <CODE>{proc_lib,init_p,5}</CODE> is returned if no information about the initial call can be found. It is assumed that the caller knows that the process has been spawned with the <CODE>proc_lib</CODE> module.

        <P><CODE>PidOrPinfo</CODE> can either be a Pid,
        an integer tuple (from which a pid can be created), or the
        process information of a process (fetched through a
        <CODE>erlang:process_info/1</CODE> function call).

        <P>This function is used by the c:I/0 and c:regs/0 functions 
        in order to present process information.
</UL>
<H3>See Also</H3>
<UL>
<P>error_logger(3)
</UL>
<H3>AUTHORS</H3>
<UL>
Magnus Fr&#246;berg - support@erlang.ericsson.se<BR>
</UL>
<CENTER>
<HR>
<FONT SIZE=-1>stdlib 1.10<BR>
Copyright &copy; 1991-2001
<A HREF="http://www.erlang.se">Ericsson Utvecklings AB</A><BR>
<!--#include virtual="/ssi/otp_footer.html"-->
</FONT>
</CENTER>
</BODY>
</HTML>