NAME

       eprof - A Time Profiling Tool for Erlang

DESCRIPTION

       The module eprof provides a set of functions for time profiling of Erlang programs to find
       out how the execution time is used. The profiling is done using  the  Erlang  trace  BIFs.
       Tracing of local function calls for a specified set of processes is enabled when profiling
       is begun, and disabled when profiling is stopped.

       When using Eprof, expect a slowdown in program execution.

EXPORTS

       start() -> {ok, Pid} | {error, Reason}

              Types:

                 Pid = pid()
                 Reason = {already_started, Pid}

              Starts the Eprof server which holds the internal state of the collected data.

       start_profiling(Rootset) -> profiling | {error, Reason}

       start_profiling(Rootset, Pattern) -> profiling | {error, Reason}

       start_profiling(Rootset, Pattern, Options) ->
                          profiling | {error, Reason}

              Types:

                 Rootset = [atom() | pid()]
                 Pattern = trace_pattern_mfa()
                 Options = [set_on_spawn | {set_on_spawn, boolean()}]
                 Reason = term()
                 trace_pattern_mfa() = {atom(), atom(), arity() | '_'}

              Starts profiling for the processes in Rootset (and any new processes  spawned  from
              them).  Information  about  activity in any profiled process is stored in the Eprof
              database.

              Rootset is a list of pids and registered names.

              The function returns profiling if tracing could be enabled  for  all  processes  in
              Rootset, or error otherwise.

              A  pattern  can be selected to narrow the profiling. For instance a specific module
              can be selected, and only the code executed in that module will be profiled.

              The set_on_spawn option will active call time tracing for all processes spawned  by
              processes in the rootset. This is the default behaviour.

       stop_profiling() -> profiling_stopped | profiling_already_stopped

              Stops profiling started with start_profiling/1 or profile/1.

       profile(Fun) -> {ok, Value} | {error, Reason}

       profile(Fun, Options) -> {ok, Value} | {error, Reason}

       profile(Rootset) -> profiling | {error, Reason}

       profile(Rootset, Fun) -> {ok, Value} | {error, Reason}

       profile(Rootset, Fun, Pattern) -> {ok, Value} | {error, Reason}

       profile(Rootset, Module, Function, Args) ->
                  {ok, Value} | {error, Reason}

       profile(Rootset, Fun, Pattern, Options) ->
                  {ok, Value} | {error, Reason}

       profile(Rootset, Module, Function, Args, Pattern) ->
                  {ok, Value} | {error, Reason}

       profile(Rootset, Module, Function, Args, Pattern, Options) ->
                  {ok, Value} | {error, Reason}

              Types:

                 Rootset = [atom() | pid()]
                 Module = module()
                 Function = atom()
                 Args = [term()]
                 Pattern = trace_pattern_mfa()
                 Options = [set_on_spawn | {set_on_spawn, boolean()}]
                 Value = Reason = term()
                 trace_pattern_mfa() = {atom(), atom(), arity() | '_'}

              This   function   first   spawns   a   process   P   which   evaluates   Fun()   or
              apply(Module,Function,Args). Then, it starts profiling for P and the  processes  in
              Rootset  (and  any  new processes spawned from them). Information about activity in
              any profiled process is stored in the Eprof database.

              Rootset is a list of pids and registered names.

              If tracing could be enabled for P  and  all  processes  in  Rootset,  the  function
              returns {ok,Value} when Fun()/apply returns with the value Value, or {error,Reason}
              if Fun()/apply fails with exit reason Reason. Otherwise it returns {error,  Reason}
              immediately.

              The  set_on_spawn option will active call time tracing for all processes spawned by
              processes in the rootset. This is the default behaviour.

              The programmer must ensure that the function given as argument is truly synchronous
              and that no work continues after the function has returned a value.

       analyze() -> ok | nothing_to_analyze

       analyze(Type) -> ok | nothing_to_analyze

       analyze(Type, Options) -> ok | nothing_to_analyze

              Types:

                 Type = analyze_type()
                 Options = [Option]
                 Option = {filter, Filter} | {sort, Sort}
                 Filter = [{calls, integer() >= 0} | {time, float()}]
                 Sort = time | calls | mfa
                 analyze_type() = procs | total

              Call  this  function  when  profiling  has  been stopped to display the results per
              process, that is:

                * how much time has been used by each process, and

                * in which function calls this time has been spent.

              Call analyze with total option when profiling  has  been  stopped  to  display  the
              results per function call, that is in which function calls the time has been spent.

              Time is shown as percentage of total time and as absolute time.

       log(File) -> ok

              Types:

                 File = atom() | file:filename()

              This  function ensures that the results displayed by analyze/0,1,2 are printed both
              to the file File and the screen.

       stop() -> stopped

              Stops the Eprof server.