aboutsummaryrefslogtreecommitdiffstats
path: root/system/doc/efficiency_guide/commoncaveats.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2015-03-12 15:35:13 +0100
committerBjörn Gustavsson <[email protected]>2015-03-12 15:38:25 +0100
commit6513fc5eb55b306e2b1088123498e6c50b9e7273 (patch)
tree986a133cb88ddeaeb0292f99af67e4d1015d1f62 /system/doc/efficiency_guide/commoncaveats.xml
parent42a0387e886ddbf60b0e2cb977758e2ca74954ae (diff)
downloadotp-6513fc5eb55b306e2b1088123498e6c50b9e7273.tar.gz
otp-6513fc5eb55b306e2b1088123498e6c50b9e7273.tar.bz2
otp-6513fc5eb55b306e2b1088123498e6c50b9e7273.zip
Update Efficiency Guide
Language cleaned up by the technical writers xsipewe and tmanevik from Combitech. Proofreading and corrections by Björn Gustavsson.
Diffstat (limited to 'system/doc/efficiency_guide/commoncaveats.xml')
-rw-r--r--system/doc/efficiency_guide/commoncaveats.xml135
1 files changed, 65 insertions, 70 deletions
diff --git a/system/doc/efficiency_guide/commoncaveats.xml b/system/doc/efficiency_guide/commoncaveats.xml
index 551b0a03e6..71991d342f 100644
--- a/system/doc/efficiency_guide/commoncaveats.xml
+++ b/system/doc/efficiency_guide/commoncaveats.xml
@@ -18,7 +18,6 @@
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
-
</legalnotice>
<title>Common Caveats</title>
@@ -29,49 +28,50 @@
<file>commoncaveats.xml</file>
</header>
- <p>Here we list a few modules and BIFs to watch out for, and not only
+ <p>This section lists a few modules and BIFs to watch out for, not only
from a performance point of view.</p>
<section>
- <title>The timer module</title>
+ <title>Timer Module</title>
<p>Creating timers using <seealso
marker="erts:erlang#erlang:send_after/3">erlang:send_after/3</seealso>
- and <seealso marker="erts:erlang#erlang:start_timer/3">erlang:start_timer/3</seealso>
+ and
+ <seealso marker="erts:erlang#erlang:start_timer/3">erlang:start_timer/3</seealso>
+,
is much more efficient than using the timers provided by the
- <seealso marker="stdlib:timer">timer</seealso> module. The
- <c>timer</c> module uses a separate process to manage the timers,
- and that process can easily become overloaded if many processes
+ <seealso marker="stdlib:timer">timer</seealso> module in STDLIB.
+ The <c>timer</c> module uses a separate process to manage the timers.
+ That process can easily become overloaded if many processes
create and cancel timers frequently (especially when using the
SMP emulator).</p>
- <p>The functions in the <c>timer</c> module that do not manage timers (such as
- <c>timer:tc/3</c> or <c>timer:sleep/1</c>), do not call the timer-server process
- and are therefore harmless.</p>
+ <p>The functions in the <c>timer</c> module that do not manage timers
+ (such as <c>timer:tc/3</c> or <c>timer:sleep/1</c>), do not call the
+ timer-server process and are therefore harmless.</p>
</section>
<section>
<title>list_to_atom/1</title>
- <p>Atoms are not garbage-collected. Once an atom is created, it will never
- be removed. The emulator will terminate if the limit for the number
- of atoms (1048576 by default) is reached.</p>
+ <p>Atoms are not garbage-collected. Once an atom is created, it is never
+ removed. The emulator terminates if the limit for the number
+ of atoms (1,048,576 by default) is reached.</p>
- <p>Therefore, converting arbitrary input strings to atoms could be
- dangerous in a system that will run continuously.
- If only certain well-defined atoms are allowed as input, you can use
+ <p>Therefore, converting arbitrary input strings to atoms can be
+ dangerous in a system that runs continuously.
+ If only certain well-defined atoms are allowed as input,
<seealso marker="erts:erlang#list_to_existing_atom/1">list_to_existing_atom/1</seealso>
+ can be used to
to guard against a denial-of-service attack. (All atoms that are allowed
- must have been created earlier, for instance by simply using all of them
+ must have been created earlier, for example, by simply using all of them
in a module and loading that module.)</p>
<p>Using <c>list_to_atom/1</c> to construct an atom that is passed to
- <c>apply/3</c> like this</p>
-
+ <c>apply/3</c> as follows, is quite expensive and not recommended
+ in time-critical code:</p>
<code type="erl">
-apply(list_to_atom("some_prefix"++Var), foo, Args)</code>
-
- <p>is quite expensive and is not recommended in time-critical code.</p>
+apply(list_to_atom("some_prefix"++Var), foo, Args)</code>
</section>
<section>
@@ -81,25 +81,25 @@ apply(list_to_atom("some_prefix"++Var), foo, Args)</code>
length of the list, as opposed to <c>tuple_size/1</c>, <c>byte_size/1</c>,
and <c>bit_size/1</c>, which all execute in constant time.</p>
- <p>Normally you don't have to worry about the speed of <c>length/1</c>,
- because it is efficiently implemented in C. In time critical-code, though,
- you might want to avoid it if the input list could potentially be very long.</p>
+ <p>Normally, there is no need to worry about the speed of <c>length/1</c>,
+ because it is efficiently implemented in C. In time-critical code,
+ you might want to avoid it if the input list could potentially be very
+ long.</p>
<p>Some uses of <c>length/1</c> can be replaced by matching.
- For instance, this code</p>
-
+ For example, the following code:</p>
<code type="erl">
foo(L) when length(L) >= 3 ->
...</code>
- <p>can be rewritten to</p>
+ <p>can be rewritten to:</p>
<code type="erl">
foo([_,_,_|_]=L) ->
...</code>
- <p>(One slight difference is that <c>length(L)</c> will fail if the <c>L</c>
- is an improper list, while the pattern in the second code fragment will
- accept an improper list.)</p>
+ <p>One slight difference is that <c>length(L)</c> fails if <c>L</c>
+ is an improper list, while the pattern in the second code fragment
+ accepts an improper list.</p>
</section>
<section>
@@ -107,50 +107,49 @@ foo([_,_,_|_]=L) ->
<p><seealso marker="erts:erlang#setelement/3">setelement/3</seealso>
copies the tuple it modifies. Therefore, updating a tuple in a loop
- using <c>setelement/3</c> will create a new copy of the tuple every time.</p>
+ using <c>setelement/3</c> creates a new copy of the tuple every time.</p>
<p>There is one exception to the rule that the tuple is copied.
If the compiler clearly can see that destructively updating the tuple would
- give exactly the same result as if the tuple was copied, the call to
- <c>setelement/3</c> will be replaced with a special destructive setelement
- instruction. In the following code sequence</p>
-
+ give the same result as if the tuple was copied, the call to
+ <c>setelement/3</c> is replaced with a special destructive <c>setelement</c>
+ instruction. In the following code sequence, the first <c>setelement/3</c>
+ call copies the tuple and modifies the ninth element:</p>
<code type="erl">
multiple_setelement(T0) ->
T1 = setelement(9, T0, bar),
T2 = setelement(7, T1, foobar),
setelement(5, T2, new_value).</code>
- <p>the first <c>setelement/3</c> call will copy the tuple and modify the
- ninth element. The two following <c>setelement/3</c> calls will modify
+ <p>The two following <c>setelement/3</c> calls modify
the tuple in place.</p>
- <p>For the optimization to be applied, <em>all</em> of the followings conditions
+ <p>For the optimization to be applied, <em>all</em> the followings conditions
must be true:</p>
<list type="bulleted">
<item>The indices must be integer literals, not variables or expressions.</item>
<item>The indices must be given in descending order.</item>
- <item>There must be no calls to other function in between the calls to
+ <item>There must be no calls to another function in between the calls to
<c>setelement/3</c>.</item>
<item>The tuple returned from one <c>setelement/3</c> call must only be used
in the subsequent call to <c>setelement/3</c>.</item>
</list>
- <p>If it is not possible to structure the code as in the <c>multiple_setelement/1</c>
+ <p>If the code cannot be structured as in the <c>multiple_setelement/1</c>
example, the best way to modify multiple elements in a large tuple is to
- convert the tuple to a list, modify the list, and convert the list back to
+ convert the tuple to a list, modify the list, and convert it back to
a tuple.</p>
</section>
<section>
<title>size/1</title>
- <p><c>size/1</c> returns the size for both tuples and binary.</p>
+ <p><c>size/1</c> returns the size for both tuples and binaries.</p>
- <p>Using the new BIFs <c>tuple_size/1</c> and <c>byte_size/1</c> introduced
- in R12B gives the compiler and run-time system more opportunities for
- optimization. A further advantage is that the new BIFs could help Dialyzer
+ <p>Using the new BIFs <c>tuple_size/1</c> and <c>byte_size/1</c>, introduced
+ in R12B, gives the compiler and the runtime system more opportunities for
+ optimization. Another advantage is that the new BIFs can help Dialyzer to
find more bugs in your program.</p>
</section>
@@ -159,22 +158,21 @@ multiple_setelement(T0) ->
<p>It is usually more efficient to split a binary using matching
instead of calling the <c>split_binary/2</c> function.
Furthermore, mixing bit syntax matching and <c>split_binary/2</c>
- may prevent some optimizations of bit syntax matching.</p>
+ can prevent some optimizations of bit syntax matching.</p>
<p><em>DO</em></p>
<code type="none"><![CDATA[
<<Bin1:Num/binary,Bin2/binary>> = Bin,]]></code>
<p><em>DO NOT</em></p>
<code type="none">
- {Bin1,Bin2} = split_binary(Bin, Num)
- </code>
+ {Bin1,Bin2} = split_binary(Bin, Num)</code>
</section>
<section>
- <title>The '--' operator</title>
- <p>Note that the '<c>--</c>' operator has a complexity
- proportional to the product of the length of its operands,
- meaning that it will be very slow if both of its operands
+ <title>Operator "--"</title>
+ <p>The "<c>--</c>" operator has a complexity
+ proportional to the product of the length of its operands.
+ This means that the operator is very slow if both of its operands
are long lists:</p>
<p><em>DO NOT</em></p>
@@ -182,42 +180,39 @@ multiple_setelement(T0) ->
HugeList1 -- HugeList2]]></code>
<p>Instead use the <seealso marker="stdlib:ordsets">ordsets</seealso>
- module:</p>
+ module in STDLIB:</p>
<p><em>DO</em></p>
<code type="none">
HugeSet1 = ordsets:from_list(HugeList1),
HugeSet2 = ordsets:from_list(HugeList2),
- ordsets:subtract(HugeSet1, HugeSet2)
- </code>
+ ordsets:subtract(HugeSet1, HugeSet2)</code>
- <p>Obviously, that code will not work if the original order
+ <p>Obviously, that code does not work if the original order
of the list is important. If the order of the list must be
- preserved, do like this:</p>
+ preserved, do as follows:</p>
<p><em>DO</em></p>
<code type="none"><![CDATA[
Set = gb_sets:from_list(HugeList2),
[E || E <- HugeList1, not gb_sets:is_element(E, Set)]]]></code>
- <p>Subtle note 1: This code behaves differently from '<c>--</c>'
- if the lists contain duplicate elements. (One occurrence
- of an element in HugeList2 will remove <em>all</em>
+ <note><p>This code behaves differently from "<c>--</c>"
+ if the lists contain duplicate elements (one occurrence
+ of an element in HugeList2 removes <em>all</em>
occurrences in HugeList1.)</p>
+ <p>Also, this code compares lists elements using the
+ "<c>==</c>" operator, while "<c>--</c>" uses the "<c>=:=</c>" operator.
+ If that difference is important, <c>sets</c> can be used instead of
+ <c>gb_sets</c>, but <c>sets:from_list/1</c> is much
+ slower than <c>gb_sets:from_list/1</c> for long lists.</p></note>
- <p>Subtle note 2: This code compares lists elements using the
- '<c>==</c>' operator, while '<c>--</c>' uses the '<c>=:=</c>'. If
- that difference is important, <c>sets</c> can be used instead of
- <c>gb_sets</c>, but note that <c>sets:from_list/1</c> is much
- slower than <c>gb_sets:from_list/1</c> for long lists.</p>
-
- <p>Using the '<c>--</c>' operator to delete an element
+ <p>Using the "<c>--</c>" operator to delete an element
from a list is not a performance problem:</p>
<p><em>OK</em></p>
<code type="none">
- HugeList1 -- [Element]
- </code>
+ HugeList1 -- [Element]</code>
</section>