← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to system/doc/efficiency_guide/README

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
system/doc/efficiency_guide/README
 
1
Benchmark framework
 
2
-------------------
 
3
 
 
4
This benchmark framework consists of the files:
 
5
bench.erl - see bench module below
 
6
bench.hrl - Defines some useful macros
 
7
all.erl   - see all module below
 
8
        
 
9
bench module 
 
10
-----------
 
11
 
 
12
The module bench is a generic module that measures execution time 
 
13
of functions in callback modules and writes an html-report on the outcome.
 
14
 
 
15
When you execute the function bench:run/0 it will compile and run all
 
16
benchmark modules in the current directory.
 
17
 
 
18
all module
 
19
-----------
 
20
 
 
21
In the all module there is a function called releases/0 that you can
 
22
edit to contain all your erlang installations and then you can
 
23
run your benchmarks on several erlang versions using only one command i.e.
 
24
all:run().
 
25
 
 
26
Requirements on callback modules
 
27
---------------------------------
 
28
 
 
29
* A callback module must be named <callbackModuleName>_bm.erl 
 
30
 
 
31
* The module must export the function benchmarks/0 that must return:
 
32
  {Iterations, [Name1,Name2...]} where Iterations is the number of
 
33
  times each benchmark should be run.  Name1, Name2 and so one are the
 
34
  name of exported functions in the module.
 
35
 
 
36
* The exported functions Name1 etc. must take one argument i.e. the number
 
37
  of iterations and should return the atom ok.
 
38
 
 
39
* The functions in a benchmark module should represent different
 
40
  ways/different sequential algorithms for doing something. And the
 
41
  result will be how fast they are compared to each other.
 
42
 
 
43
Files created
 
44
--------------
 
45
 
 
46
Files that are created in the current directory are *.bmres and
 
47
index.html. The file(s) with the extension "bmres" are an intermediate
 
48
representation of the benchmark results and is only meant to be read
 
49
by the reporting mechanism defined in bench.erl. The index.html file
 
50
is the report telling you how good the benchmarks are in comparison to
 
51
each other.  If you run your test on several erlang releases the
 
52
html-file will include the result for all versions.
 
53
 
 
54
 
 
55
Pitfalls 
 
56
---------
 
57
To get meaningful measurements, you should make sure that:
 
58
 
 
59
* The total execution time is at least several seconds.
 
60
 
 
61
* That any time spent in setup before entering the measurement loop is very
 
62
  small compared to the total time.
 
63
 
 
64
* That time spent by the loop itself is small compared to the total execution
 
65
  time
 
66
  
 
67
Consider the following example of a benchmark function that does
 
68
a local function call.
 
69
 
 
70
local_call(0) -> ok;
 
71
local_call(Iter) ->
 
72
    foo(), % Local function call         
 
73
    local_call(Iter-1).
 
74
 
 
75
The problem is that both "foo()" and "local_call(Iter-1)" takes about
 
76
the same amount of time. To get meaningful figures you'll need to make
 
77
sure that the loop overhead will not be visible. In this case we can
 
78
take help of a macro in bench.hrl to repeat the local function call
 
79
many times, making sure that time spent calling the local function is
 
80
relatively much longer than the time spent iterating. Of course, all
 
81
benchmarks in the same module must be repeated the same number of
 
82
times; thus external_call will look like
 
83
 
 
84
external_call(0) -> ok;
 
85
external_call(Iter) ->
 
86
    ?rep20(?MODULE:foo()),
 
87
    external_call(Iter-1).
 
88
 
 
89
This technique is only necessary if the operation we are testing executes
 
90
really fast.
 
91
 
 
92
If you for instance want to test a sort routine we can keep it simple:
 
93
 
 
94
sorted(Iter) ->
 
95
    do_sort(Iter, lists:seq(0, 63)).
 
96
 
 
97
do_sort(0, List) -> ok;
 
98
do_sort(Iter, List) ->
 
99
    lists:sort(List),
 
100
    do_sort(Iter-1, List).
 
101
 
 
102
The call to lists:seq/2 is only done once. The loop overhead in the
 
103
do_sort/2 function is small compared to the execution time of lists:sort/1.
 
104
 
 
105
Error handling
 
106
---------------
 
107
 
 
108
Any error enforced by a callback module will result in exit of the benchmark
 
109
program and an errormessage that should give a good idea of what is wrong.
 
110
 
 
111
 
 
112
 
 
113
 
 
114
 
 
115
 
 
116
 
 
117
 
 
118
 
 
119
 
 
120
 
 
121
 
 
122