1erlang(3) Erlang Module Definition erlang(3)
2
6 erlang - The Erlang BIFs.
7
9 By convention, most Built-In Functions (BIFs) are included in this mod‐
10 ule. Some of the BIFs are viewed more or less as part of the Erlang
11 programming language and are auto-imported. Thus, it is not necessary
12 to specify the module name. For example, the calls atom_to_list(erlang)
13 and erlang:atom_to_list(erlang) are identical.
14 Auto-imported BIFs are listed without module prefix. BIFs listed with
16 module prefix are not auto-imported.
17 BIFs can fail for various reasons. All BIFs fail with reason badarg if
19 they are called with arguments of an incorrect type. The other reasons
20 are described in the description of each individual BIF.
21 Some BIFs can be used in guard tests and are marked with "Allowed in
23 guard tests".
24
26 ext_binary() = binary()
27 A binary data object, structured according to the Erlang exter‐
29 nal term format.
30 ext_iovec() = iovec()
32 A term of type iovec(), structured according to the Erlang ex‐
34 ternal term format.
35 iovec() = [binary()]
37 A list of binaries. This datatype is useful to use together with
39 enif_inspect_iovec.
40 message_queue_data() = off_heap | on_heap
42 See process_flag(message_queue_data, MQD).
44 timestamp() =
46 {MegaSecs :: integer() >= 0,
47 Secs :: integer() >= 0,
48 MicroSecs :: integer() >= 0}
49 See erlang:timestamp/0.
51 time_unit() =
53 integer() >= 1 |
54 second | millisecond | microsecond | nanosecond | native |
55 perf_counter |
56 deprecated_time_unit()
57 Supported time unit representations:
59 PartsPerSecond :: integer() >= 1:
61 Time unit expressed in parts per second. That is, the time
62 unit equals 1/PartsPerSecond second.
63 second:
65 Symbolic representation of the time unit represented by the
66 integer 1.
67 millisecond:
69 Symbolic representation of the time unit represented by the
70 integer 1000.
71 microsecond:
73 Symbolic representation of the time unit represented by the
74 integer 1000_000.
75 nanosecond:
77 Symbolic representation of the time unit represented by the
78 integer 1000_000_000.
79 native:
81 Symbolic representation of the native time unit used by the
82 Erlang runtime system.
83 The native time unit is determined at runtime system start,
85 and remains the same until the runtime system terminates. If
86 a runtime system is stopped and then started again (even on
87 the same machine), the native time unit of the new runtime
88 system instance can differ from the native time unit of the
89 old runtime system instance.
90 One can get an approximation of the native time unit by
92 calling erlang:convert_time_unit(1, second, native). The re‐
93 sult equals the number of whole native time units per sec‐
94 ond. If the number of native time units per second does not
95 add up to a whole number, the result is rounded downwards.
96 Note:
98 The value of the native time unit gives you more or less no
99 information about the quality of time values. It sets a limit
100 for the resolution and for the precision of time values, but
101 it gives no information about the accuracy of time values.
102 The resolution of the native time unit and the resolution of
103 time values can differ significantly.
104 perf_counter:
107 Symbolic representation of the performance counter time unit
108 used by the Erlang runtime system.
109 The perf_counter time unit behaves much in the same way as
111 the native time unit. That is, it can differ between runtime
112 restarts. To get values of this type, call
113 os:perf_counter/0.
114 deprecated_time_unit():
116 Deprecated symbolic representations kept for backwards-com‐
117 patibility.
118 The time_unit/0 type can be extended. To convert time values be‐
120 tween time units, use erlang:convert_time_unit/3.
121 deprecated_time_unit() =
123 seconds | milli_seconds | micro_seconds | nano_seconds
124 The time_unit() type also consist of the following deprecated
126 symbolic time units:
127 seconds:
129 Same as second.
130 milli_seconds:
132 Same as millisecond.
133 micro_seconds:
135 Same as microsecond.
136 nano_seconds:
138 Same as nanosecond.
139 dist_handle()
141 An opaque handle identifing a distribution channel.
143 nif_resource()
145 An opaque handle identifing a NIF resource object .
147 spawn_opt_option() =
149 link | monitor |
150 {priority, Level :: priority_level()} |
151 {fullsweep_after, Number :: integer() >= 0} |
152 {min_heap_size, Size :: integer() >= 0} |
153 {min_bin_vheap_size, VSize :: integer() >= 0} |
154 {max_heap_size, Size :: max_heap_size()} |
155 {message_queue_data, MQD :: message_queue_data()}
156 Options for spawn_opt().
158 priority_level() = low | normal | high | max
160 Process priority level. For more info see process_flag(priority,
162 Level)
163 max_heap_size() =
165 integer() >= 0 |
166 #{size => integer() >= 0,
167 kill => boolean(),
168 error_logger => boolean()}
169 Process max heap size configuration. For more info see
171 process_flag(max_heap_size, MaxHeapSize)
172 message_queue_data() = off_heap | on_heap
174 Process message queue data configuration. For more information,
176 see process_flag(message_queue_data, MQD)
177
179 abs(Float) -> float()
180 abs(Int) -> integer() >= 0
182 Types:
184 Int = integer()
186 Returns an integer or float that is the arithmetical absolute
188 value of Float or Int, for example:
189 > abs(-3.33).
191 3.33
192 > abs(-3).
193 3
194 Allowed in guard tests.
196 erlang:adler32(Data) -> integer() >= 0
198 Types:
200 Data = iodata()
202 Computes and returns the adler32 checksum for Data.
204 erlang:adler32(OldAdler, Data) -> integer() >= 0
206 Types:
208 OldAdler = integer() >= 0
210 Data = iodata()
211 Continues computing the adler32 checksum by combining the previ‐
213 ous checksum, OldAdler, with the checksum of Data.
214 The following code:
216 X = erlang:adler32(Data1),
218 Y = erlang:adler32(X,Data2).
219 assigns the same value to Y as this:
221 Y = erlang:adler32([Data1,Data2]).
223 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
225 integer() >= 0
226 Types:
228 FirstAdler = SecondAdler = SecondSize = integer() >= 0
230 Combines two previously computed adler32 checksums. This compu‐
232 tation requires the size of the data object for the second
233 checksum to be known.
234 The following code:
236 Y = erlang:adler32(Data1),
238 Z = erlang:adler32(Y,Data2).
239 assigns the same value to Z as this:
241 X = erlang:adler32(Data1),
243 Y = erlang:adler32(Data2),
244 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
245 erlang:append_element(Tuple1, Term) -> Tuple2
247 Types:
249 Tuple1 = Tuple2 = tuple()
251 Term = term()
252 Returns a new tuple that has one element more than Tuple1, and
254 contains the elements in Tuple1 followed by Term as the last el‐
255 ement. Semantically equivalent to list_to_tuple(tu‐
256 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
257 > erlang:append_element({one, two}, three).
259 {one,two,three}
260 apply(Fun, Args) -> term()
262 Types:
264 Fun = function()
266 Args = [term()]
267 Calls a fun, passing the elements in Args as arguments.
269 If the number of elements in the arguments are known at compile
271 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
272 Warning:
274 Earlier, Fun could also be specified as {Module, Function},
275 equivalent to apply(Module, Function, Args). This use is depre‐
276 cated and will stop working in a future release.
277 apply(Module, Function, Args) -> term()
280 Types:
282 Module = module()
284 Function = atom()
285 Args = [term()]
286 Returns the result of applying Function in Module to Args. The
288 applied function must be exported from Module. The arity of the
289 function is the length of Args. Example:
290 > apply(lists, reverse, [[a, b, c]]).
292 [c,b,a]
293 > apply(erlang, atom_to_list, ['Erlang']).
294 "Erlang"
295 If the number of arguments are known at compile time, the call
297 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
298 Failure: error_handler:undefined_function/3 is called if the ap‐
300 plied function is not exported. The error handler can be rede‐
301 fined (see process_flag/2). If error_handler is undefined, or if
302 the user has redefined the default error_handler so the replace‐
303 ment module is undefined, an error with reason undef is gener‐
304 ated.
305 atom_to_binary(Atom) -> binary()
307 Types:
309 Atom = atom()
311 The same as atom_to_binary(Atom, utf8).
313 atom_to_binary(Atom, Encoding) -> binary()
315 Types:
317 Atom = atom()
319 Encoding = latin1 | unicode | utf8
320 Returns a binary corresponding to the text representation of
322 Atom. If Encoding is latin1, one byte exists for each character
323 in the text representation. If Encoding is utf8 or unicode, the
324 characters are encoded using UTF-8 where characters may require
325 multiple bytes.
326 Note:
328 As from Erlang/OTP 20, atoms can contain any Unicode character
329 and atom_to_binary(Atom, latin1) may fail if the text represen‐
330 tation for Atom contains a Unicode character > 255.
331 Example:
334 > atom_to_binary('Erlang', latin1).
336 <<"Erlang">>
337 atom_to_list(Atom) -> string()
339 Types:
341 Atom = atom()
343 Returns a string corresponding to the text representation of
345 Atom, for example:
346 > atom_to_list('Erlang').
348 "Erlang"
349 binary_part(Subject, PosLen) -> binary()
351 Types:
353 Subject = binary()
355 PosLen = {Start :: integer() >= 0, Length :: integer()}
356 Extracts the part of the binary described by PosLen.
358 Negative length can be used to extract bytes at the end of a bi‐
360 nary, for example:
361 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
363 2> binary_part(Bin,{byte_size(Bin), -5}).
364 <<6,7,8,9,10>>
365 Failure: badarg if PosLen in any way references outside the bi‐
367 nary.
368 Start is zero-based, that is:
370 1> Bin = <<1,2,3>>
372 2> binary_part(Bin,{0,2}).
373 <<1,2>>
374 For details about the PosLen semantics, see binary(3).
376 Allowed in guard tests.
378 binary_part(Subject, Start, Length) -> binary()
380 Types:
382 Subject = binary()
384 Start = integer() >= 0
385 Length = integer()
386 The same as binary_part(Subject, {Start, Length}).
388 Allowed in guard tests.
390 binary_to_atom(Binary) -> atom()
392 Types:
394 Binary = binary()
396 The same as binary_to_atom(Binary, utf8).
398 binary_to_atom(Binary, Encoding) -> atom()
400 Types:
402 Binary = binary()
404 Encoding = latin1 | unicode | utf8
405 Returns the atom whose text representation is Binary. If Encod‐
407 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
408 quences.
409 Note:
411 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
412 of encoding any Unicode character. Earlier versions would fail
413 if the binary contained Unicode characters > 255. For more in‐
414 formation about Unicode support in atoms, see the note on UTF-8
415 encoded atoms in section "External Term Format" in the User's
416 Guide.
417 Examples:
420 > binary_to_atom(<<"Erlang">>, latin1).
422 > binary_to_atom(<<1024/utf8>>, utf8).
423 binary_to_existing_atom(Binary) -> atom()
425 Types:
427 Binary = binary()
429 The same as binary_to_existing_atom (Binary, utf8).
431 binary_to_existing_atom(Binary, Encoding) -> atom()
433 Types:
435 Binary = binary()
437 Encoding = latin1 | unicode | utf8
438 As binary_to_atom/2, but the atom must exist.
440 Failure: badarg if the atom does not exist.
442 Note:
444 Note that the compiler may optimize away atoms. For example, the
445 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
446 that expression is the only mention of the atom some_atom in the
447 containing module, the atom will not be created when the module
448 is loaded, and a subsequent call to binary_to_exist‐
449 ing_atom(<<"some_atom">>, utf8) will fail.
450 binary_to_float(Binary) -> float()
453 Types:
455 Binary = binary()
457 Returns the float whose text representation is Binary, for exam‐
459 ple:
460 > binary_to_float(<<"2.2017764e+0">>).
462 2.2017764
463 Failure: badarg if Binary contains a bad representation of a
465 float.
466 binary_to_integer(Binary) -> integer()
468 Types:
470 Binary = binary()
472 Returns an integer whose text representation is Binary, for ex‐
474 ample:
475 > binary_to_integer(<<"123">>).
477 123
478 Failure: badarg if Binary contains a bad representation of an
480 integer.
481 binary_to_integer(Binary, Base) -> integer()
483 Types:
485 Binary = binary()
487 Base = 2..36
488 Returns an integer whose text representation in base Base is Bi‐
490 nary, for example:
491 > binary_to_integer(<<"3FF">>, 16).
493 1023
494 Failure: badarg if Binary contains a bad representation of an
496 integer.
497 binary_to_list(Binary) -> [byte()]
499 Types:
501 Binary = binary()
503 Returns a list of integers corresponding to the bytes of Binary.
505 binary_to_list(Binary, Start, Stop) -> [byte()]
507 Types:
509 Binary = binary()
511 Start = Stop = integer() >= 1
512 1..byte_size(Binary)
513 As binary_to_list/1, but returns a list of integers correspond‐
515 ing to the bytes from position Start to position Stop in Binary.
516 The positions in the binary are numbered starting from 1.
517 Note:
519 The one-based indexing for binaries used by this function is
520 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
521 instead. All functions in module binary consistently use zero-
522 based indexing.
523 binary_to_term(Binary) -> term()
526 Types:
528 Binary = ext_binary()
530 Returns an Erlang term that is the result of decoding binary ob‐
532 ject Binary, which must be encoded according to the Erlang ex‐
533 ternal term format.
534 > Bin = term_to_binary(hello).
536 <<131,100,0,5,104,101,108,108,111>>
537 > hello = binary_to_term(Bin).
538 hello
539 Warning:
542 When decoding binaries from untrusted sources, consider using
543 binary_to_term/2 to prevent Denial of Service attacks.
544 See also term_to_binary/1 and binary_to_term/2.
547 binary_to_term(Binary, Opts) -> term() | {term(), Used}
549 Types:
551 Binary = ext_binary()
553 Opt = safe | used
554 Opts = [Opt]
555 Used = integer() >= 1
556 As binary_to_term/1, but takes these options:
558 safe:
560 Use this option when receiving binaries from an untrusted
561 source.
562 When enabled, it prevents decoding data that can be used to
564 attack the Erlang system. In the event of receiving unsafe
565 data, decoding fails with a badarg error.
566 This prevents creation of new atoms directly, creation of
568 new atoms indirectly (as they are embedded in certain struc‐
569 tures, such as process identifiers, refs, and funs), and
570 creation of new external function references. None of those
571 resources are garbage collected, so unchecked creation of
572 them can exhaust available memory.
573 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
575 ** exception error: bad argument
576 > hello.
577 hello
578 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
579 hello
580 used:
583 Changes the return value to {Term, Used} where Used is the
584 number of bytes actually read from Binary.
585 > Input = <<131,100,0,5,"hello","world">>.
587 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
588 > {Term, Used} = binary_to_term(Input, [used]).
589 {hello, 9}
590 > split_binary(Input, Used).
591 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
592 Failure: badarg if safe is specified and unsafe data is decoded.
595 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
597 ing_atom/1.
598 bit_size(Bitstring) -> integer() >= 0
600 Types:
602 Bitstring = bitstring()
604 Returns an integer that is the size in bits of Bitstring, for
606 example:
607 > bit_size(<<433:16,3:3>>).
609 19
610 > bit_size(<<1,2,3>>).
611 24
612 Allowed in guard tests.
614 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
616 Types:
618 Bitstring = bitstring()
620 Returns a list of integers corresponding to the bytes of Bit‐
622 string. If the number of bits in the binary is not divisible by
623 8, the last element of the list is a bitstring containing the
624 remaining 1-7 bits.
625 erlang:bump_reductions(Reductions) -> true
627 Types:
629 Reductions = integer() >= 1
631 This implementation-dependent function increments the reduction
633 counter for the calling process. In the Beam emulator, the re‐
634 duction counter is normally incremented by one for each function
635 and BIF call. A context switch is forced when the counter
636 reaches the maximum number of reductions for a process (2000 re‐
637 ductions in Erlang/OTP R12B).
638 Warning:
640 This BIF can be removed in a future version of the Beam machine
641 without prior warning. It is unlikely to be implemented in other
642 Erlang implementations.
643 byte_size(Bitstring) -> integer() >= 0
646 Types:
648 Bitstring = bitstring()
650 Returns an integer that is the number of bytes needed to contain
652 Bitstring. That is, if the number of bits in Bitstring is not
653 divisible by 8, the resulting number of bytes is rounded up. Ex‐
654 amples:
655 > byte_size(<<433:16,3:3>>).
657 3
658 > byte_size(<<1,2,3>>).
659 3
660 Allowed in guard tests.
662 erlang:cancel_timer(TimerRef) -> Result
664 Types:
666 TimerRef = reference()
668 Time = integer() >= 0
669 Result = Time | false
670 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
672 Ref, []).
673 erlang:cancel_timer(TimerRef, Options) -> Result | ok
675 Types:
677 TimerRef = reference()
679 Async = Info = boolean()
680 Option = {async, Async} | {info, Info}
681 Options = [Option]
682 Time = integer() >= 0
683 Result = Time | false
684 Cancels a timer that has been created by erlang:start_timer or
686 erlang:send_after. TimerRef identifies the timer, and was re‐
687 turned by the BIF that created the timer.
688 Options:
690 {async, Async}:
692 Asynchronous request for cancellation. Async defaults to
693 false, which causes the cancellation to be performed syn‐
694 chronously. When Async is set to true, the cancel operation
695 is performed asynchronously. That is, cancel_timer() sends
696 an asynchronous request for cancellation to the timer ser‐
697 vice that manages the timer, and then returns ok.
698 {info, Info}:
700 Requests information about the Result of the cancellation.
701 Info defaults to true, which means the Result is given. When
702 Info is set to false, no information about the result of the
703 cancellation is given.
704 * When Async is false: if Info is true, the Result is re‐
706 turned by erlang:cancel_timer(). otherwise ok is returned.
707 * When Async is true: if Info is true, a message on the form
709 {cancel_timer, TimerRef, Result} is sent to the caller of
710 erlang:cancel_timer() when the cancellation operation has
711 been performed, otherwise no message is sent.
712 More Options may be added in the future.
714 If Result is an integer, it represents the time in milliseconds
716 left until the canceled timer would have expired.
717 If Result is false, a timer corresponding to TimerRef could not
719 be found. This can be either because the timer had expired, al‐
720 ready had been canceled, or because TimerRef never corresponded
721 to a timer. Even if the timer had expired, it does not tell you
722 if the time-out message has arrived at its destination yet.
723 Note:
725 The timer service that manages the timer can be co-located with
726 another scheduler than the scheduler that the calling process is
727 executing on. If so, communication with the timer service takes
728 much longer time than if it is located locally. If the calling
729 process is in critical path, and can do other things while wait‐
730 ing for the result of this operation, or is not interested in
731 the result of the operation, you want to use option {async,
732 true}. If using option {async, false}, the calling process
733 blocks until the operation has been performed.
734 See also erlang:send_after/4, erlang:start_timer/4, and er‐
737 lang:read_timer/2.
738 ceil(Number) -> integer()
740 Types:
742 Number = number()
744 Returns the smallest integer not less than Number. For example:
746 > ceil(5.5).
748 6
749 Allowed in guard tests.
751 check_old_code(Module) -> boolean()
753 Types:
755 Module = module()
757 Returns true if Module has old code, otherwise false.
759 See also code(3).
761 check_process_code(Pid, Module) -> CheckResult
763 Types:
765 Pid = pid()
767 Module = module()
768 CheckResult = boolean()
769 The same as check_process_code(Pid, Module, []).
771 check_process_code(Pid, Module, OptionList) -> CheckResult | async
773 Types:
775 Pid = pid()
777 Module = module()
778 RequestId = term()
779 Option = {async, RequestId} | {allow_gc, boolean()}
780 OptionList = [Option]
781 CheckResult = boolean() | aborted
782 Checks if the node local process identified by Pid executes old
784 code for Module.
785 Options:
787 {allow_gc, boolean()}:
789 Determines if garbage collection is allowed when performing
790 the operation. If {allow_gc, false} is passed, and a garbage
791 collection is needed to determine the result of the opera‐
792 tion, the operation is aborted (see information on CheckRe‐
793 sult below). The default is to allow garbage collection,
794 that is, {allow_gc, true}.
795 {async, RequestId}:
797 The function check_process_code/3 returns the value async
798 immediately after the request has been sent. When the re‐
799 quest has been processed, the process that called this func‐
800 tion is passed a message on the form {check_process_code,
801 RequestId, CheckResult}.
802 If Pid equals self(), and no async option has been passed, the
804 operation is performed at once. Otherwise a request for the op‐
805 eration is sent to the process identified by Pid, and is handled
806 when appropriate. If no async option has been passed, the caller
807 blocks until CheckResult is available and can be returned.
808 CheckResult informs about the result of the request as follows:
810 true:
812 The process identified by Pid executes old code for Module.
813 That is, the current call of the process executes old code
814 for this module, or the process has references to old code
815 for this module, or the process contains funs that refer‐
816 ences old code for this module.
817 false:
819 The process identified by Pid does not execute old code for
820 Module.
821 aborted:
823 The operation was aborted, as the process needed to be
824 garbage collected to determine the operation result, and the
825 operation was requested by passing option {allow_gc, false}.
826 Note:
828 Up until ERTS version 8.*, the check process code operation
829 checks for all types of references to the old code. That is, di‐
830 rect references (e.g. return addresses on the process stack),
831 indirect references (funs in process context), and references to
832 literals in the code.
833 As of ERTS version 9.0, the check process code operation only
835 checks for direct references to the code. Indirect references
836 via funs will be ignored. If such funs exist and are used after
837 a purge of the old code, an exception will be raised upon usage
838 (same as the case when the fun is received by the process after
839 the purge). Literals will be taken care of (copied) at a later
840 stage. This behavior can as of ERTS version 8.1 be enabled when
841 building OTP, and will automatically be enabled if dirty sched‐
842 uler support is enabled.
843 See also code(3).
846 Failures:
848 badarg:
850 If Pid is not a node local process identifier.
851 badarg:
853 If Module is not an atom.
854 badarg:
856 If OptionList is an invalid list of options.
857 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
859 Types:
861 Time = ConvertedTime = integer()
863 FromUnit = ToUnit = time_unit()
864 Converts the Time value of time unit FromUnit to the correspond‐
866 ing ConvertedTime value of time unit ToUnit. The result is
867 rounded using the floor function.
868 Warning:
870 You can lose accuracy and precision when converting between time
871 units. To minimize such loss, collect all data at native time
872 unit and do the conversion on the end result.
873 erlang:crc32(Data) -> integer() >= 0
876 Types:
878 Data = iodata()
880 Computes and returns the crc32 (IEEE 802.3 style) checksum for
882 Data.
883 erlang:crc32(OldCrc, Data) -> integer() >= 0
885 Types:
887 OldCrc = integer() >= 0
889 Data = iodata()
890 Continues computing the crc32 checksum by combining the previous
892 checksum, OldCrc, with the checksum of Data.
893 The following code:
895 X = erlang:crc32(Data1),
897 Y = erlang:crc32(X,Data2).
898 assigns the same value to Y as this:
900 Y = erlang:crc32([Data1,Data2]).
902 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
904 integer() >= 0
905 Types:
907 FirstCrc = SecondCrc = SecondSize = integer() >= 0
909 Combines two previously computed crc32 checksums. This computa‐
911 tion requires the size of the data object for the second check‐
912 sum to be known.
913 The following code:
915 Y = erlang:crc32(Data1),
917 Z = erlang:crc32(Y,Data2).
918 assigns the same value to Z as this:
920 X = erlang:crc32(Data1),
922 Y = erlang:crc32(Data2),
923 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
924 date() -> Date
926 Types:
928 Date = calendar:date()
930 Returns the current date as {Year, Month, Day}.
932 The time zone and Daylight Saving Time correction depend on the
934 underlying OS. Example:
935 > date().
937 {1995,2,19}
938 erlang:decode_packet(Type, Bin, Options) ->
940 {ok, Packet, Rest} |
941 {more, Length} |
942 {error, Reason}
943 Types:
945 Type =
947 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
948 line | http | http_bin | httph | httph_bin
949 Bin = binary()
950 Options = [Opt]
951 Opt =
952 {packet_size, integer() >= 0} |
953 {line_length, integer() >= 0}
954 Packet = binary() | HttpPacket
955 Rest = binary()
956 Length = integer() >= 0 | undefined
957 Reason = term()
958 HttpPacket =
959 HttpRequest | HttpResponse | HttpHeader | http_eoh |
960 HttpError
961 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
962 sion}
963 HttpResponse =
964 {http_response, HttpVersion, integer(), HttpString}
965 HttpHeader =
966 {http_header,
967 integer(),
968 HttpField,
969 UnmodifiedField :: HttpString,
970 Value :: HttpString}
971 HttpError = {http_error, HttpString}
972 HttpMethod =
973 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
974 'TRACE' | HttpString
975 HttpUri =
976 '*' |
977 {absoluteURI,
978 http | https,
979 Host :: HttpString,
980 Port :: inet:port_number() | undefined,
981 Path :: HttpString} |
982 {scheme, Scheme :: HttpString, HttpString} |
983 {abs_path, HttpString} |
984 HttpString
985 HttpVersion =
986 {Major :: integer() >= 0, Minor :: integer() >= 0}
987 HttpField =
988 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
989 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
990 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
991 |
992 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
993 'If-Match' | 'If-None-Match' | 'If-Range' |
994 'If-Unmodified-Since' | 'Max-Forwards' |
995 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
996 Agent' |
997 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
998 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
999 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1000 'Content-Encoding' | 'Content-Language' | 'Content-
1001 Length' |
1002 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1003 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1004 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1005 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1006 'Proxy-Connection' | HttpString
1007 HttpString = string() | binary()
1008 Decodes the binary Bin according to the packet protocol speci‐
1010 fied by Type. Similar to the packet handling done by sockets
1011 with option {packet,Type}.
1012 If an entire packet is contained in Bin, it is returned together
1014 with the remainder of the binary as {ok,Packet,Rest}.
1015 If Bin does not contain the entire packet, {more,Length} is re‐
1017 turned. Length is either the expected total size of the packet,
1018 or undefined if the expected packet size is unknown. de‐
1019 code_packet can then be called again with more data added.
1020 If the packet does not conform to the protocol format, {er‐
1022 ror,Reason} is returned.
1023 Types:
1025 raw | 0:
1027 No packet handling is done. The entire binary is returned
1028 unless it is empty.
1029 1 | 2 | 4:
1031 Packets consist of a header specifying the number of bytes
1032 in the packet, followed by that number of bytes. The length
1033 of the header can be one, two, or four bytes; the order of
1034 the bytes is big-endian. The header is stripped off when the
1035 packet is returned.
1036 line:
1038 A packet is a line-terminated by a delimiter byte, default
1039 is the latin-1 newline character. The delimiter byte is in‐
1040 cluded in the returned packet unless the line was truncated
1041 according to option line_length.
1042 asn1 | cdr | sunrm | fcgi | tpkt:
1044 The header is not stripped off.
1045 The meanings of the packet types are as follows:
1047 asn1 - ASN.1 BER:
1049 sunrm - Sun's RPC encoding:
1052 cdr - CORBA (GIOP 1.1):
1055 fcgi - Fast CGI:
1058 tpkt - TPKT format [RFC1006]:
1061 http | httph | http_bin | httph_bin:
1064 The Hypertext Transfer Protocol. The packets are returned
1065 with the format according to HttpPacket described earlier. A
1066 packet is either a request, a response, a header, or an end
1067 of header mark. Invalid lines are returned as HttpError.
1068 Recognized request methods and header fields are returned as
1070 atoms. Others are returned as strings. Strings of unrecog‐
1071 nized header fields are formatted with only capital letters
1072 first and after hyphen characters, for example, "Sec-Web‐
1073 socket-Key". Header field names are also returned in Unmodi‐
1074 fiedField as strings, without any conversion or formatting.
1075 The protocol type http is only to be used for the first line
1077 when an HttpRequest or an HttpResponse is expected. The fol‐
1078 lowing calls are to use httph to get HttpHeaders until
1079 http_eoh is returned, which marks the end of the headers and
1080 the beginning of any following message body.
1081 The variants http_bin and httph_bin return strings (Http‐
1083 String) as binaries instead of lists.
1084 Options:
1086 {packet_size, integer() >= 0}:
1088 Sets the maximum allowed size of the packet body. If the
1089 packet header indicates that the length of the packet is
1090 longer than the maximum allowed length, the packet is con‐
1091 sidered invalid. Defaults to 0, which means no size limit.
1092 {line_length, integer() >= 0}:
1094 For packet type line, lines longer than the indicated length
1095 are truncated.
1096 Option line_length also applies to http* packet types as an
1098 alias for option packet_size if packet_size itself is not
1099 set. This use is only intended for backward compatibility.
1100 {line_delimiter, 0 =< byte() =< 255}:
1102 For packet type line, sets the delimiting byte. Default is
1103 the latin-1 character $\n.
1104 Examples:
1106 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1108 {ok,<<"abc">>,<<"d">>}
1109 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1110 {more,6}
1111 erlang:delete_element(Index, Tuple1) -> Tuple2
1113 Types:
1115 Index = integer() >= 1
1117 1..tuple_size(Tuple1)
1118 Tuple1 = Tuple2 = tuple()
1119 Returns a new tuple with element at Index removed from tuple Tu‐
1121 ple1, for example:
1122 > erlang:delete_element(2, {one, two, three}).
1124 {one,three}
1125 delete_module(Module) -> true | undefined
1127 Types:
1129 Module = module()
1131 Makes the current code for Module become old code and deletes
1133 all references for this module from the export table. Returns
1134 undefined if the module does not exist, otherwise true.
1135 Warning:
1137 This BIF is intended for the code server (see code(3)) and is
1138 not to be used elsewhere.
1139 Failure: badarg if there already is an old version of Module.
1142 demonitor(MonitorRef) -> true
1144 Types:
1146 MonitorRef = reference()
1148 If MonitorRef is a reference that the calling process obtained
1150 by calling monitor/2, this monitoring is turned off. If the mon‐
1151 itoring is already turned off, nothing happens.
1152 Once demonitor(MonitorRef) has returned, it is guaranteed that
1154 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1155 tor, will be placed in the caller message queue in the future.
1156 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1157 placed in the caller message queue before the call. It is there‐
1158 fore usually advisable to remove such a 'DOWN' message from the
1159 message queue after monitoring has been stopped. demonitor(Moni‐
1160 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1161 this cleanup is wanted.
1162 Note:
1164 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1165 asynchronously, that is, the monitor was active until the "de‐
1166 monitor signal" reached the monitored entity. This had one unde‐
1167 sirable effect. You could never know when you were guaranteed
1168 not to receive a DOWN message because of the monitor.
1169 The current behavior can be viewed as two combined operations:
1171 asynchronously send a "demonitor signal" to the monitored entity
1172 and ignore any future results of the monitor.
1173 Failure: It is an error if MonitorRef refers to a monitoring
1176 started by another process. Not all such cases are cheap to
1177 check. If checking is cheap, the call fails with badarg, for ex‐
1178 ample if MonitorRef is a remote reference.
1179 demonitor(MonitorRef, OptionList) -> boolean()
1181 Types:
1183 MonitorRef = reference()
1185 OptionList = [Option]
1186 Option = flush | info
1187 The returned value is true unless info is part of OptionList.
1189 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1191 Ref).
1192 Options:
1194 flush:
1196 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1197 one, from the caller message queue after monitoring has been
1198 stopped.
1199 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1201 following, but more efficient:
1202 demonitor(MonitorRef),
1204 receive
1205 {_, MonitorRef, _, _, _} ->
1206 true
1207 after 0 ->
1208 true
1209 end
1210 info:
1212 The returned value is one of the following:
1213 true:
1215 The monitor was found and removed. In this case, no 'DOWN'
1216 message corresponding to this monitor has been delivered
1217 and will not be delivered.
1218 false:
1220 The monitor was not found and could not be removed. This
1221 probably because someone already has placed a 'DOWN' mes‐
1222 sage corresponding to this monitor in the caller message
1223 queue.
1224 If option info is combined with option flush, false is re‐
1226 turned if a flush was needed, otherwise true.
1227 Note:
1229 More options can be added in a future release.
1230 Failures:
1233 badarg:
1235 If OptionList is not a list.
1236 badarg:
1238 If Option is an invalid option.
1239 badarg:
1241 The same failure as for demonitor/1.
1242 disconnect_node(Node) -> boolean() | ignored
1244 Types:
1246 Node = node()
1248 Forces the disconnection of a node. This appears to the node
1250 Node as if the local node has crashed. This BIF is mainly used
1251 in the Erlang network authentication protocols.
1252 Returns true if disconnection succeeds, otherwise false. If the
1254 local node is not alive, ignored is returned.
1255 erlang:display(Term) -> true
1257 Types:
1259 Term = term()
1261 Prints a text representation of Term on the standard output.
1263 Warning:
1265 This BIF is intended for debugging only.
1266 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1269 Types:
1271 Size = integer() >= 0
1273 DHandle = dist_handle()
1274 Data = iovec()
1275 Get distribution channel data from the local node that is to be
1277 passed to the remote node. The distribution channel is identi‐
1278 fied by DHandle. If no data is available, the atom none is re‐
1279 turned. One can request to be informed by a message when more
1280 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1281 tion(DHandle).
1282 The returned value when there are data available depends on the
1284 value of the get_size option configured on the distribution
1285 channel identified by DHandle. For more information see the doc‐
1286 umentation of the get_size option for the er‐
1287 lang:dist_ctrl_set_opt/3 function.
1288 Note:
1290 Only the process registered as distribution controller for the
1291 distribution channel identified by DHandle is allowed to call
1292 this function.
1293 This function is used when implementing an alternative distribu‐
1296 tion carrier using processes as distribution controllers. DHan‐
1297 dle is retrived via the callback f_handshake_complete. More in‐
1298 formation can be found in the documentation of ERTS User's Guide
1299 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1300 bution ➜ Distribution Module.
1301 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1303 Types:
1305 DHandle = dist_handle()
1307 Value = boolean()
1308 Returns the value of the get_size option on the distribution
1310 channel identified by DHandle. For more information see the doc‐
1311 umentation of the get_size option for the er‐
1312 lang:dist_ctrl_set_opt/3 function.
1313 Note:
1315 Only the process registered as distribution controller for the
1316 distribution channel identified by DHandle is allowed to call
1317 this function.
1318 This function is used when implementing an alternative distribu‐
1321 tion carrier using processes as distribution controllers. DHan‐
1322 dle is retrived via the callback f_handshake_complete. More in‐
1323 formation can be found in the documentation of ERTS User's Guide
1324 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1325 bution ➜ Distribution Module.
1326 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1328 Types:
1330 DHandle = dist_handle()
1332 Request notification when more data is available to fetch using
1334 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1335 identified by DHandle. When more data is present, the caller
1336 will be sent the message dist_data. Once a dist_data messages
1337 has been sent, no more dist_data messages will be sent until the
1338 dist_ctrl_get_data_notification/1 function has been called
1339 again.
1340 Note:
1342 Only the process registered as distribution controller for the
1343 distribution channel identified by DHandle is allowed to call
1344 this function.
1345 This function is used when implementing an alternative distribu‐
1348 tion carrier using processes as distribution controllers. DHan‐
1349 dle is retrived via the callback f_handshake_complete. More in‐
1350 formation can be found in the documentation of ERTS User's Guide
1351 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1352 bution ➜ Distribution Module.
1353 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1355 Types:
1357 DHandle = dist_handle()
1359 InputHandler = pid()
1360 Register an alternate input handler process for the distribution
1362 channel identified by DHandle. Once this function has been
1363 called, InputHandler is the only process allowed to call er‐
1364 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1365 fing this distribution channel.
1366 Note:
1368 Only the process registered as distribution controller for the
1369 distribution channel identified by DHandle is allowed to call
1370 this function.
1371 This function is used when implementing an alternative distribu‐
1374 tion carrier using processes as distribution controllers. DHan‐
1375 dle is retrived via the callback f_handshake_complete. More in‐
1376 formation can be found in the documentation of ERTS User's Guide
1377 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1378 bution ➜ Distribution Module.
1379 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1381 Types:
1383 DHandle = dist_handle()
1385 Data = iodata()
1386 Deliver distribution channel data from a remote node to the lo‐
1388 cal node.
1389 Note:
1391 Only the process registered as distribution controller for the
1392 distribution channel identified by DHandle is allowed to call
1393 this function unless an alternate input handler process has been
1394 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1395 putHandler). If an alternate input handler has been registered,
1396 only the registered input handler process is allowed to call
1397 this function.
1398 This function is used when implementing an alternative distribu‐
1401 tion carrier using processes as distribution controllers. DHan‐
1402 dle is retrived via the callback f_handshake_complete. More in‐
1403 formation can be found in the documentation of ERTS User's Guide
1404 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1405 bution ➜ Distribution Module.
1406 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1408 OldValue
1409 Types:
1411 DHandle = dist_handle()
1413 Value = OldValue = boolean()
1414 Sets the value of the get_size option on the distribution chan‐
1416 nel identified by DHandle. This option controls the return value
1417 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1418 equals DHandle used when setting this option. When the get_size
1419 option is:
1420 false:
1422 and there are distribution data available, a call to er‐
1423 lang:dist_ctrl_get_data(DHandle) will just return Data to
1424 pass over the channel. This is the default value of the
1425 get_size option.
1426 true:
1428 and there are distribution data available, a call to er‐
1429 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1430 over the channel as well as the Size of Data in bytes. This
1431 is returned as a tuple on the form {Size, Data}.
1432 All options are set to default when a channel is closed.
1434 Note:
1436 Only the process registered as distribution controller for the
1437 distribution channel identified by DHandle is allowed to call
1438 this function.
1439 This function is used when implementing an alternative distribu‐
1442 tion carrier using processes as distribution controllers. DHan‐
1443 dle is retrived via the callback f_handshake_complete. More in‐
1444 formation can be found in the documentation of ERTS User's Guide
1445 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1446 bution ➜ Distribution Module.
1447 element(N, Tuple) -> term()
1449 Types:
1451 N = integer() >= 1
1453 1..tuple_size(Tuple)
1454 Tuple = tuple()
1455 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1457 ple:
1458 > element(2, {a, b, c}).
1460 b
1461 Allowed in guard tests.
1463 erase() -> [{Key, Val}]
1465 Types:
1467 Key = Val = term()
1469 Returns the process dictionary and deletes it, for example:
1471 > put(key1, {1, 2, 3}),
1473 put(key2, [a, b, c]),
1474 erase().
1475 [{key1,{1,2,3}},{key2,[a,b,c]}]
1476 erase(Key) -> Val | undefined
1478 Types:
1480 Key = Val = term()
1482 Returns the value Val associated with Key and deletes it from
1484 the process dictionary. Returns undefined if no value is associ‐
1485 ated with Key. Example:
1486 > put(key1, {merry, lambs, are, playing}),
1488 X = erase(key1),
1489 {X, erase(key1)}.
1490 {{merry,lambs,are,playing},undefined}
1491 error(Reason) -> no_return()
1493 Types:
1495 Reason = term()
1497 Stops the execution of the calling process with the reason Rea‐
1499 son, where Reason is any term. The exit reason is {Reason,
1500 Where}, where Where is a list of the functions most recently
1501 called (the current function first). As evaluating this function
1502 causes the process to terminate, it has no return value. Exam‐
1503 ple:
1504 > catch error(foobar).
1506 {'EXIT',{foobar,[{shell,apply_fun,3,
1507 [{file,"shell.erl"},{line,906}]},
1508 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1509 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1510 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1511 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1512 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1513 error(Reason, Args) -> no_return()
1516 Types:
1518 Reason = term()
1520 Args = [term()]
1521 Stops the execution of the calling process with the reason Rea‐
1523 son, where Reason is any term. The exit reason is {Reason,
1524 Where}, where Where is a list of the functions most recently
1525 called (the current function first). Args is expected to be the
1526 list of arguments for the current function; in Beam it is used
1527 to provide the arguments for the current function in the term
1528 Where. As evaluating this function causes the process to termi‐
1529 nate, it has no return value.
1530 exit(Reason) -> no_return()
1532 Types:
1534 Reason = term()
1536 Stops the execution of the calling process with exit reason Rea‐
1538 son, where Reason is any term. As evaluating this function
1539 causes the process to terminate, it has no return value. Exam‐
1540 ple:
1541 > exit(foobar).
1543 ** exception exit: foobar
1544 > catch exit(foobar).
1545 {'EXIT',foobar}
1546 exit(Pid, Reason) -> true
1548 Types:
1550 Pid = pid() | port()
1552 Reason = term()
1553 Sends an exit signal with exit reason Reason to the process or
1555 port identified by Pid.
1556 The following behavior applies if Reason is any term, except
1558 normal or kill:
1559 * If Pid is not trapping exits, Pid itself exits with exit
1561 reason Reason.
1562 * If Pid is trapping exits, the exit signal is transformed
1564 into a message {'EXIT', From, Reason} and delivered to the
1565 message queue of Pid.
1566 * From is the process identifier of the process that sent the
1568 exit signal. See also process_flag/2.
1569 If Reason is the atom normal, Pid does not exit. If it is trap‐
1571 ping exits, the exit signal is transformed into a message
1572 {'EXIT', From, normal} and delivered to its message queue.
1573 If Reason is the atom kill, that is, if exit(Pid, kill) is
1575 called, an untrappable exit signal is sent to Pid, which uncon‐
1576 ditionally exits with exit reason killed.
1577 erlang:external_size(Term) -> integer() >= 0
1579 Types:
1581 Term = term()
1583 Calculates, without doing the encoding, the maximum byte size
1585 for a term encoded in the Erlang external term format. The fol‐
1586 lowing condition applies always:
1587 > Size1 = byte_size(term_to_binary(Term)),
1589 > Size2 = erlang:external_size(Term),
1590 > true = Size1 =< Size2.
1591 true
1592 This is equivalent to a call to:
1594 erlang:external_size(Term, [])
1596 erlang:external_size(Term, Options) -> integer() >= 0
1598 Types:
1600 Term = term()
1602 Options = [{minor_version, Version :: integer() >= 0}]
1603 Calculates, without doing the encoding, the maximum byte size
1605 for a term encoded in the Erlang external term format. The fol‐
1606 lowing condition applies always:
1607 > Size1 = byte_size(term_to_binary(Term, Options)),
1609 > Size2 = erlang:external_size(Term, Options),
1610 > true = Size1 =< Size2.
1611 true
1612 Option {minor_version, Version} specifies how floats are en‐
1614 coded. For a detailed description, see term_to_binary/2.
1615 float(Number) -> float()
1617 Types:
1619 Number = number()
1621 Returns a float by converting Number to a float, for example:
1623 > float(55).
1625 55.0
1626 Allowed in guard tests.
1628 Note:
1630 If used on the top level in a guard, it tests whether the argu‐
1631 ment is a floating point number; for clarity, use is_float/1 in‐
1632 stead.
1633 When float/1 is used in an expression in a guard, such as
1635 'float(A) == 4.0', it converts a number as described earlier.
1636 float_to_binary(Float) -> binary()
1639 Types:
1641 Float = float()
1643 The same as float_to_binary(Float,[{scientific,20}]).
1645 float_to_binary(Float, Options) -> binary()
1647 Types:
1649 Float = float()
1651 Options = [Option]
1652 Option =
1653 {decimals, Decimals :: 0..253} |
1654 {scientific, Decimals :: 0..249} |
1655 compact
1656 Returns a binary corresponding to the text representation of
1658 Float using fixed decimal point formatting. Options behaves in
1659 the same way as float_to_list/2. Examples:
1660 > float_to_binary(7.12, [{decimals, 4}]).
1662 <<"7.1200">>
1663 > float_to_binary(7.12, [{decimals, 4}, compact]).
1664 <<"7.12">>
1665 float_to_list(Float) -> string()
1667 Types:
1669 Float = float()
1671 The same as float_to_list(Float,[{scientific,20}]).
1673 float_to_list(Float, Options) -> string()
1675 Types:
1677 Float = float()
1679 Options = [Option]
1680 Option =
1681 {decimals, Decimals :: 0..253} |
1682 {scientific, Decimals :: 0..249} |
1683 compact
1684 Returns a string corresponding to the text representation of
1686 Float using fixed decimal point formatting.
1687 Available options:
1689 * If option decimals is specified, the returned value contains
1691 at most Decimals number of digits past the decimal point. If
1692 the number does not fit in the internal static buffer of 256
1693 bytes, the function throws badarg.
1694 * If option compact is specified, the trailing zeros at the
1696 end of the list are truncated. This option is only meaning‐
1697 ful together with option decimals.
1698 * If option scientific is specified, the float is formatted
1700 using scientific notation with Decimals digits of precision.
1701 * If Options is [], the function behaves as float_to_list/1.
1703 Examples:
1705 > float_to_list(7.12, [{decimals, 4}]).
1707 "7.1200"
1708 > float_to_list(7.12, [{decimals, 4}, compact]).
1709 "7.12"
1710 floor(Number) -> integer()
1712 Types:
1714 Number = number()
1716 Returns the largest integer not greater than Number. For exam‐
1718 ple:
1719 > floor(-10.5).
1721 -11
1722 Allowed in guard tests.
1724 erlang:fun_info(Fun) -> [{Item, Info}]
1726 Types:
1728 Fun = function()
1730 Item =
1731 arity | env | index | name | module | new_index |
1732 new_uniq |
1733 pid | type | uniq
1734 Info = term()
1735 Returns a list with information about the fun Fun. Each list el‐
1737 ement is a tuple. The order of the tuples is undefined, and more
1738 tuples can be added in a future release.
1739 Warning:
1741 This BIF is mainly intended for debugging, but it can sometimes
1742 be useful in library functions that need to verify, for example,
1743 the arity of a fun.
1744 Two types of funs have slightly different semantics:
1747 * A fun created by fun M:F/A is called an external fun. Call‐
1749 ing it will always call the function F with arity A in the
1750 latest code for module M. Notice that module M does not even
1751 need to be loaded when the fun fun M:F/A is created.
1752 * All other funs are called local. When a local fun is called,
1754 the same version of the code that created the fun is called
1755 (even if a newer version of the module has been loaded).
1756 The following elements are always present in the list for both
1758 local and external funs:
1759 {type, Type}:
1761 Type is local or external.
1762 {module, Module}:
1764 Module (an atom) is the module name.
1765 If Fun is a local fun, Module is the module in which the fun
1767 is defined.
1768 If Fun is an external fun, Module is the module that the fun
1770 refers to.
1771 {name, Name}:
1773 Name (an atom) is a function name.
1774 If Fun is a local fun, Name is the name of the local func‐
1776 tion that implements the fun. (This name was generated by
1777 the compiler, and is only of informational use. As it is a
1778 local function, it cannot be called directly.) If no code is
1779 currently loaded for the fun, [] is returned instead of an
1780 atom.
1781 If Fun is an external fun, Name is the name of the exported
1783 function that the fun refers to.
1784 {arity, Arity}:
1786 Arity is the number of arguments that the fun is to be
1787 called with.
1788 {env, Env}:
1790 Env (a list) is the environment or free variables for the
1791 fun. For external funs, the returned list is always empty.
1792 The following elements are only present in the list if Fun is
1794 local:
1795 {pid, Pid}:
1797 Pid is the process identifier of the process that originally
1798 created the fun.
1799 It might point to the init process if the Fun was statically
1801 allocated when module was loaded (this optimisation is per‐
1802 formed for local functions that do not capture the environ‐
1803 ment).
1804 {index, Index}:
1806 Index (an integer) is an index into the module fun table.
1807 {new_index, Index}:
1809 Index (an integer) is an index into the module fun table.
1810 {new_uniq, Uniq}:
1812 Uniq (a binary) is a unique value for this fun. It is calcu‐
1813 lated from the compiled code for the entire module.
1814 {uniq, Uniq}:
1816 Uniq (an integer) is a unique value for this fun. As from
1817 Erlang/OTP R15, this integer is calculated from the compiled
1818 code for the entire module. Before Erlang/OTP R15, this in‐
1819 teger was based on only the body of the fun.
1820 erlang:fun_info(Fun, Item) -> {Item, Info}
1822 Types:
1824 Fun = function()
1826 Item = fun_info_item()
1827 Info = term()
1828 fun_info_item() =
1829 arity | env | index | name | module | new_index | new_uniq |
1830 pid | type | uniq
1831 Returns information about Fun as specified by Item, in the form
1833 {Item,Info}.
1834 For any fun, Item can be any of the atoms module, name, arity,
1836 env, or type.
1837 For a local fun, Item can also be any of the atoms index,
1839 new_index, new_uniq, uniq, and pid. For an external fun, the
1840 value of any of these items is always the atom undefined.
1841 See erlang:fun_info/1.
1843 erlang:fun_to_list(Fun) -> string()
1845 Types:
1847 Fun = function()
1849 Returns a string corresponding to the text representation of
1851 Fun.
1852 erlang:function_exported(Module, Function, Arity) -> boolean()
1854 Types:
1856 Module = module()
1858 Function = atom()
1859 Arity = arity()
1860 Returns true if the module Module is loaded and contains an ex‐
1862 ported function Function/Arity, or if there is a BIF (a built-in
1863 function implemented in C) with the specified name, otherwise
1864 returns false.
1865 Note:
1867 This function used to return false for BIFs before Erlang/OTP
1868 18.0.
1869 garbage_collect() -> true
1872 Forces an immediate garbage collection of the executing process.
1874 The function is not to be used unless it has been noticed (or
1875 there are good reasons to suspect) that the spontaneous garbage
1876 collection will occur too late or not at all.
1877 Warning:
1879 Improper use can seriously degrade system performance.
1880 garbage_collect(Pid) -> GCResult
1883 Types:
1885 Pid = pid()
1887 GCResult = boolean()
1888 The same as garbage_collect(Pid, []).
1890 garbage_collect(Pid, OptionList) -> GCResult | async
1892 Types:
1894 Pid = pid()
1896 RequestId = term()
1897 Option = {async, RequestId} | {type, major | minor}
1898 OptionList = [Option]
1899 GCResult = boolean()
1900 Garbage collects the node local process identified by Pid.
1902 Option:
1904 {async, RequestId}:
1906 The function garbage_collect/2 returns the value async imme‐
1907 diately after the request has been sent. When the request
1908 has been processed, the process that called this function is
1909 passed a message on the form {garbage_collect, RequestId,
1910 GCResult}.
1911 {type, 'major' | 'minor'}:
1913 Triggers garbage collection of requested type. Default value
1914 is 'major', which would trigger a fullsweep GC. The option
1915 'minor' is considered a hint and may lead to either minor or
1916 major GC run.
1917 If Pid equals self(), and no async option has been passed, the
1919 garbage collection is performed at once, that is, the same as
1920 calling garbage_collect/0. Otherwise a request for garbage col‐
1921 lection is sent to the process identified by Pid, and will be
1922 handled when appropriate. If no async option has been passed,
1923 the caller blocks until GCResult is available and can be re‐
1924 turned.
1925 GCResult informs about the result of the garbage collection re‐
1927 quest as follows:
1928 true:
1930 The process identified by Pid has been garbage collected.
1931 false:
1933 No garbage collection was performed, as the process identi‐
1934 fied by Pid terminated before the request could be satis‐
1935 fied.
1936 Notice that the same caveats apply as for garbage_collect/0.
1938 Failures:
1940 badarg:
1942 If Pid is not a node local process identifier.
1943 badarg:
1945 If OptionList is an invalid list of options.
1946 get() -> [{Key, Val}]
1948 Types:
1950 Key = Val = term()
1952 Returns the process dictionary as a list of {Key, Val} tuples,
1954 for example:
1955 > put(key1, merry),
1957 put(key2, lambs),
1958 put(key3, {are, playing}),
1959 get().
1960 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
1961 get(Key) -> Val | undefined
1963 Types:
1965 Key = Val = term()
1967 Returns the value Val associated with Key in the process dictio‐
1969 nary, or undefined if Key does not exist. Example:
1970 > put(key1, merry),
1972 put(key2, lambs),
1973 put({any, [valid, term]}, {are, playing}),
1974 get({any, [valid, term]}).
1975 {are,playing}
1976 erlang:get_cookie() -> Cookie | nocookie
1978 Types:
1980 Cookie = atom()
1982 Returns the magic cookie of the local node if the node is alive,
1984 otherwise the atom nocookie.
1985 get_keys() -> [Key]
1987 Types:
1989 Key = term()
1991 Returns a list of all keys present in the process dictionary,
1993 for example:
1994 > put(dog, {animal,1}),
1996 put(cow, {animal,2}),
1997 put(lamb, {animal,3}),
1998 get_keys().
1999 [dog,cow,lamb]
2000 get_keys(Val) -> [Key]
2002 Types:
2004 Val = Key = term()
2006 Returns a list of keys that are associated with the value Val in
2008 the process dictionary, for example:
2009 > put(mary, {1, 2}),
2011 put(had, {1, 2}),
2012 put(a, {1, 2}),
2013 put(little, {1, 2}),
2014 put(dog, {1, 3}),
2015 put(lamb, {1, 2}),
2016 get_keys({1, 2}).
2017 [mary,had,a,little,lamb]
2018 erlang:get_stacktrace() -> [stack_item()]
2020 Types:
2022 stack_item() =
2024 {Module :: module(),
2025 Function :: atom(),
2026 Arity :: arity() | (Args :: [term()]),
2027 Location ::
2028 [{file, Filename :: string()} |
2029 {line, Line :: integer() >= 1}]}
2030 Warning:
2032 erlang:get_stacktrace/0 is deprecated and will be removed in OTP
2033 24. Starting from OTP 23, erlang:get_stacktrace/0 returns [].
2034 Instead of using erlang:get_stacktrace/0 to retrieve the call
2037 stack back-trace, use the following syntax:
2038 try Expr
2040 catch
2041 Class:Reason:Stacktrace ->
2042 {Class,Reason,Stacktrace}
2043 end
2044 group_leader() -> pid()
2046 Returns the process identifier of the group leader for the
2048 process evaluating the function.
2049 Every process is a member of some process group and all groups
2051 have a group leader. All I/O from the group is channeled to the
2052 group leader. When a new process is spawned, it gets the same
2053 group leader as the spawning process. Initially, at system
2054 startup, init is both its own group leader and the group leader
2055 of all processes.
2056 group_leader(GroupLeader, Pid) -> true
2058 Types:
2060 GroupLeader = Pid = pid()
2062 Sets the group leader of Pid to GroupLeader. Typically, this is
2064 used when a process started from a certain shell is to have an‐
2065 other group leader than init.
2066 The group leader should be rarely changed in applications with a
2068 supervision tree, because OTP assumes the group leader of their
2069 processes is their application master.
2070 See also group_leader/0 and OTP design principles related to
2072 starting and stopping applications.
2073 halt() -> no_return()
2075 The same as halt(0, []). Example:
2077 > halt().
2079 os_prompt%
2080 halt(Status) -> no_return()
2082 Types:
2084 Status = integer() >= 0 | abort | string()
2086 The same as halt(Status, []). Example:
2088 > halt(17).
2090 os_prompt% echo $?
2091 17
2092 os_prompt%
2093 halt(Status, Options) -> no_return()
2095 Types:
2097 Status = integer() >= 0 | abort | string()
2099 Options = [Option]
2100 Option = {flush, boolean()}
2101 Status must be a non-negative integer, a string, or the atom
2103 abort. Halts the Erlang runtime system. Has no return value. De‐
2104 pending on Status, the following occurs:
2105 integer():
2107 The runtime system exits with integer value Status as status
2108 code to the calling environment (OS).
2109 Note:
2111 On many platforms, the OS supports only status codes 0-255. A
2112 too large status code is truncated by clearing the high bits.
2113 string():
2116 An Erlang crash dump is produced with Status as slogan. Then
2117 the runtime system exits with status code 1. The string will
2118 be truncated if longer than 200 characters.
2119 Note:
2121 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2122 was accepted in the string. Now any unicode string is valid.
2123 abort:
2126 The runtime system aborts producing a core dump, if that is
2127 enabled in the OS.
2128 For integer Status, the Erlang runtime system closes all ports
2130 and allows async threads to finish their operations before exit‐
2131 ing. To exit without such flushing, use Option as {flush,false}.
2132 For statuses string() and abort, option flush is ignored and
2134 flushing is not done.
2135 hd(List) -> term()
2137 Types:
2139 List = [term(), ...]
2141 Returns the head of List, that is, the first element, for exam‐
2143 ple:
2144 > hd([1,2,3,4,5]).
2146 1
2147 Allowed in guard tests.
2149 Failure: badarg if List is the empty list [].
2151 erlang:hibernate(Module, Function, Args) -> no_return()
2153 Types:
2155 Module = module()
2157 Function = atom()
2158 Args = [term()]
2159 Puts the calling process into a wait state where its memory al‐
2161 location has been reduced as much as possible. This is useful if
2162 the process does not expect to receive any messages soon.
2163 The process is awaken when a message is sent to it, and control
2165 resumes in Module:Function with the arguments specified by Args
2166 with the call stack emptied, meaning that the process terminates
2167 when that function returns. Thus erlang:hibernate/3 never re‐
2168 turns to its caller.
2169 If the process has any message in its message queue, the process
2171 is awakened immediately in the same way as described earlier.
2172 In more technical terms, erlang:hibernate/3 discards the call
2174 stack for the process, and then garbage collects the process.
2175 After this, all live data is in one continuous heap. The heap is
2176 then shrunken to the exact same size as the live data that it
2177 holds (even if that size is less than the minimum heap size for
2178 the process).
2179 If the size of the live data in the process is less than the
2181 minimum heap size, the first garbage collection occurring after
2182 the process is awakened ensures that the heap size is changed to
2183 a size not smaller than the minimum heap size.
2184 Notice that emptying the call stack means that any surrounding
2186 catch is removed and must be re-inserted after hibernation. One
2187 effect of this is that processes started using proc_lib (also
2188 indirectly, such as gen_server processes), are to use
2189 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2190 dler continues to work when the process wakes up.
2191 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2193 Types:
2195 Index = integer() >= 1
2197 1..tuple_size(Tuple1) + 1
2198 Tuple1 = Tuple2 = tuple()
2199 Term = term()
2200 Returns a new tuple with element Term inserted at position Index
2202 in tuple Tuple1. All elements from position Index and upwards
2203 are pushed one step higher in the new tuple Tuple2. Example:
2204 > erlang:insert_element(2, {one, two, three}, new).
2206 {one,new,two,three}
2207 integer_to_binary(Integer) -> binary()
2209 Types:
2211 Integer = integer()
2213 Returns a binary corresponding to the text representation of In‐
2215 teger, for example:
2216 > integer_to_binary(77).
2218 <<"77">>
2219 integer_to_binary(Integer, Base) -> binary()
2221 Types:
2223 Integer = integer()
2225 Base = 2..36
2226 Returns a binary corresponding to the text representation of In‐
2228 teger in base Base, for example:
2229 > integer_to_binary(1023, 16).
2231 <<"3FF">>
2232 integer_to_list(Integer) -> string()
2234 Types:
2236 Integer = integer()
2238 Returns a string corresponding to the text representation of In‐
2240 teger, for example:
2241 > integer_to_list(77).
2243 "77"
2244 integer_to_list(Integer, Base) -> string()
2246 Types:
2248 Integer = integer()
2250 Base = 2..36
2251 Returns a string corresponding to the text representation of In‐
2253 teger in base Base, for example:
2254 > integer_to_list(1023, 16).
2256 "3FF"
2257 iolist_size(Item) -> integer() >= 0
2259 Types:
2261 Item = iolist() | binary()
2263 Returns an integer, that is the size in bytes, of the binary
2265 that would be the result of iolist_to_binary(Item), for example:
2266 > iolist_size([1,2|<<3,4>>]).
2268 4
2269 iolist_to_binary(IoListOrBinary) -> binary()
2271 Types:
2273 IoListOrBinary = iolist() | binary()
2275 Returns a binary that is made from the integers and binaries in
2277 IoListOrBinary, for example:
2278 > Bin1 = <<1,2,3>>.
2280 <<1,2,3>>
2281 > Bin2 = <<4,5>>.
2282 <<4,5>>
2283 > Bin3 = <<6>>.
2284 <<6>>
2285 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2286 <<1,2,3,1,2,3,4,5,4,6>>
2287 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2289 Types:
2291 IoListOrBinary = iolist() | binary()
2293 Returns an iovec that is made from the integers and binaries in
2295 IoListOrBinary.
2296 is_alive() -> boolean()
2298 Returns true if the local node is alive (that is, if the node
2300 can be part of a distributed system), otherwise false.
2301 is_atom(Term) -> boolean()
2303 Types:
2305 Term = term()
2307 Returns true if Term is an atom, otherwise false.
2309 Allowed in guard tests.
2311 is_binary(Term) -> boolean()
2313 Types:
2315 Term = term()
2317 Returns true if Term is a binary, otherwise false.
2319 A binary always contains a complete number of bytes.
2321 Allowed in guard tests.
2323 is_bitstring(Term) -> boolean()
2325 Types:
2327 Term = term()
2329 Returns true if Term is a bitstring (including a binary), other‐
2331 wise false.
2332 Allowed in guard tests.
2334 is_boolean(Term) -> boolean()
2336 Types:
2338 Term = term()
2340 Returns true if Term is the atom true or the atom false (that
2342 is, a boolean). Otherwise returns false.
2343 Allowed in guard tests.
2345 erlang:is_builtin(Module, Function, Arity) -> boolean()
2347 Types:
2349 Module = module()
2351 Function = atom()
2352 Arity = arity()
2353 This BIF is useful for builders of cross-reference tools.
2355 Returns true if Module:Function/Arity is a BIF implemented in C,
2357 otherwise false.
2358 is_float(Term) -> boolean()
2360 Types:
2362 Term = term()
2364 Returns true if Term is a floating point number, otherwise
2366 false.
2367 Allowed in guard tests.
2369 is_function(Term) -> boolean()
2371 Types:
2373 Term = term()
2375 Returns true if Term is a fun, otherwise false.
2377 Allowed in guard tests.
2379 is_function(Term, Arity) -> boolean()
2381 Types:
2383 Term = term()
2385 Arity = arity()
2386 Returns true if Term is a fun that can be applied with Arity
2388 number of arguments, otherwise false.
2389 Allowed in guard tests.
2391 is_integer(Term) -> boolean()
2393 Types:
2395 Term = term()
2397 Returns true if Term is an integer, otherwise false.
2399 Allowed in guard tests.
2401 is_list(Term) -> boolean()
2403 Types:
2405 Term = term()
2407 Returns true if Term is a list with zero or more elements, oth‐
2409 erwise false.
2410 Allowed in guard tests.
2412 is_map(Term) -> boolean()
2414 Types:
2416 Term = term()
2418 Returns true if Term is a map, otherwise false.
2420 Allowed in guard tests.
2422 is_map_key(Key, Map) -> boolean()
2424 Types:
2426 Key = term()
2428 Map = map()
2429 Returns true if map Map contains Key and returns false if it
2431 does not contain the Key.
2432 The call fails with a {badmap,Map} exception if Map is not a
2434 map.
2435 Example:
2437 > Map = #{"42" => value}.
2439 #{"42" => value}
2440 > is_map_key("42",Map).
2441 true
2442 > is_map_key(value,Map).
2443 false
2444 Allowed in guard tests.
2446 is_number(Term) -> boolean()
2448 Types:
2450 Term = term()
2452 Returns true if Term is an integer or a floating point number.
2454 Otherwise returns false.
2455 Allowed in guard tests.
2457 is_pid(Term) -> boolean()
2459 Types:
2461 Term = term()
2463 Returns true if Term is a process identifier, otherwise false.
2465 Allowed in guard tests.
2467 is_port(Term) -> boolean()
2469 Types:
2471 Term = term()
2473 Returns true if Term is a port identifier, otherwise false.
2475 Allowed in guard tests.
2477 is_process_alive(Pid) -> boolean()
2479 Types:
2481 Pid = pid()
2483 Pid must refer to a process at the local node.
2485 Returns true if the process exists and is alive, that is, is not
2487 exiting and has not exited. Otherwise returns false.
2488 is_record(Term, RecordTag) -> boolean()
2490 Types:
2492 Term = term()
2494 RecordTag = atom()
2495 Returns true if Term is a tuple and its first element is Record‐
2497 Tag. Otherwise returns false.
2498 Note:
2500 Normally the compiler treats calls to is_record/2 especially. It
2501 emits code to verify that Term is a tuple, that its first ele‐
2502 ment is RecordTag, and that the size is correct. However, if
2503 RecordTag is not a literal atom, the BIF is_record/2 is called
2504 instead and the size of the tuple is not verified.
2505 Allowed in guard tests, if RecordTag is a literal atom.
2508 is_record(Term, RecordTag, Size) -> boolean()
2510 Types:
2512 Term = term()
2514 RecordTag = atom()
2515 Size = integer() >= 0
2516 RecordTag must be an atom.
2518 Returns true if Term is a tuple, its first element is RecordTag,
2520 and its size is Size. Otherwise returns false.
2521 Allowed in guard tests if RecordTag is a literal atom and Size
2523 is a literal integer.
2524 Note:
2526 This BIF is documented for completeness. Usually is_record/2 is
2527 to be used.
2528 is_reference(Term) -> boolean()
2531 Types:
2533 Term = term()
2535 Returns true if Term is a reference, otherwise false.
2537 Allowed in guard tests.
2539 is_tuple(Term) -> boolean()
2541 Types:
2543 Term = term()
2545 Returns true if Term is a tuple, otherwise false.
2547 Allowed in guard tests.
2549 length(List) -> integer() >= 0
2551 Types:
2553 List = [term()]
2555 Returns the length of List, for example:
2557 > length([1,2,3,4,5,6,7,8,9]).
2559 9
2560 Allowed in guard tests.
2562 link(PidOrPort) -> true
2564 Types:
2566 PidOrPort = pid() | port()
2568 Sets up and activates a link between the calling process and an‐
2570 other process or a port identified by PidOrPort. We will from
2571 here on call the identified process or port linkee. If the lin‐
2572 kee is a port, it must reside on the same node as the caller.
2573 If one of the participants of a link terminates, it will send an
2575 exit signal to the other participant. The exit signal will con‐
2576 tain the exit reason of the terminated participant. Other cases
2577 when exit signals are triggered due to a link are when no linkee
2578 exist (noproc exit reason) and when the connection between
2579 linked processes on different nodes is lost or cannot be estab‐
2580 lished (noconnection exit reason).
2581 An existing link can be removed by calling unlink/1. For more
2583 information on links and exit signals due to links, see the Pro‐
2584 cesses chapter in the Erlang Reference Manual :
2585 * Links
2587 * Sending Exit Signals
2589 * Receiving Exit Signals
2591 For historical reasons, link/1 has a strange semi-synchronous
2593 behavior when it is "cheap" to check if the linkee exists or
2594 not, and the caller does not trap exits. If the above is true
2595 and the linkee does not exist, link/1 will raise a noproc error
2596 exception. The expected behavior would instead have been that
2597 link/1 returned true, and the caller later was sent an exit sig‐
2598 nal with noproc exit reason, but this is unfortunately not the
2599 case. The noproc exception is not to be confused with an exit
2600 signal with exit reason noproc. Currently it is "cheap" to check
2601 if the linkee exists when it is supposed to reside on the same
2602 node as the calling process.
2603 The link setup and activation is performed asynchronously. If
2605 the link already exists, or if the caller attempts to create a
2606 link to itself, nothing is done. A detailed description of the
2607 link protocol can be found in the Distribution Protocol chapter
2608 of the ERTS User's Guide .
2609 Failure:
2611 * badarg if PidOrPort does not identify a process or a node
2613 local port.
2614 * noproc linkee does not exist and it is "cheap" to check if
2616 it exists as described above.
2617 list_to_atom(String) -> atom()
2619 Types:
2621 String = string()
2623 Returns the atom whose text representation is String.
2625 As from Erlang/OTP 20, String may contain any Unicode character.
2627 Earlier versions allowed only ISO-latin-1 characters as the im‐
2628 plementation did not allow Unicode characters above 255. For
2629 more information on Unicode support in atoms, see note on UTF-8
2630 encoded atoms in section "External Term Format" in the User's
2631 Guide.
2632 Example:
2634 > list_to_atom("Erlang").
2636 list_to_binary(IoList) -> binary()
2638 Types:
2640 IoList = iolist()
2642 Returns a binary that is made from the integers and binaries in
2644 IoList, for example:
2645 > Bin1 = <<1,2,3>>.
2647 <<1,2,3>>
2648 > Bin2 = <<4,5>>.
2649 <<4,5>>
2650 > Bin3 = <<6>>.
2651 <<6>>
2652 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2653 <<1,2,3,1,2,3,4,5,4,6>>
2654 list_to_bitstring(BitstringList) -> bitstring()
2656 Types:
2658 BitstringList = bitstring_list()
2660 bitstring_list() =
2661 maybe_improper_list(byte() | bitstring() | bitstring_list(),
2662 bitstring() | [])
2663 Returns a bitstring that is made from the integers and bit‐
2665 strings in BitstringList. (The last tail in BitstringList is al‐
2666 lowed to be a bitstring.) Example:
2667 > Bin1 = <<1,2,3>>.
2669 <<1,2,3>>
2670 > Bin2 = <<4,5>>.
2671 <<4,5>>
2672 > Bin3 = <<6,7:4>>.
2673 <<6,7:4>>
2674 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
2675 <<1,2,3,1,2,3,4,5,4,6,7:4>>
2676 list_to_existing_atom(String) -> atom()
2678 Types:
2680 String = string()
2682 Returns the atom whose text representation is String, but only
2684 if there already exists such atom.
2685 Failure: badarg if there does not already exist an atom whose
2687 text representation is String.
2688 Note:
2690 Note that the compiler may optimize away atoms. For example, the
2691 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
2692 that expression is the only mention of the atom some_atom in the
2693 containing module, the atom will not be created when the module
2694 is loaded, and a subsequent call to list_to_exist‐
2695 ing_atom("some_atom") will fail.
2696 list_to_float(String) -> float()
2699 Types:
2701 String = string()
2703 Returns the float whose text representation is String, for exam‐
2705 ple:
2706 > list_to_float("2.2017764e+0").
2708 2.2017764
2709 Failure: badarg if String contains a bad representation of a
2711 float.
2712 list_to_integer(String) -> integer()
2714 Types:
2716 String = string()
2718 Returns an integer whose text representation is String, for ex‐
2720 ample:
2721 > list_to_integer("123").
2723 123
2724 Failure: badarg if String contains a bad representation of an
2726 integer.
2727 list_to_integer(String, Base) -> integer()
2729 Types:
2731 String = string()
2733 Base = 2..36
2734 Returns an integer whose text representation in base Base is
2736 String, for example:
2737 > list_to_integer("3FF", 16).
2739 1023
2740 Failure: badarg if String contains a bad representation of an
2742 integer.
2743 list_to_pid(String) -> pid()
2745 Types:
2747 String = string()
2749 Returns a process identifier whose text representation is a
2751 String, for example:
2752 > list_to_pid("<0.4.1>").
2754 <0.4.1>
2755 Failure: badarg if String contains a bad representation of a
2757 process identifier.
2758 Warning:
2760 This BIF is intended for debugging and is not to be used in ap‐
2761 plication programs.
2762 list_to_port(String) -> port()
2765 Types:
2767 String = string()
2769 Returns a port identifier whose text representation is a String,
2771 for example:
2772 > list_to_port("#Port<0.4>").
2774 #Port<0.4>
2775 Failure: badarg if String contains a bad representation of a
2777 port identifier.
2778 Warning:
2780 This BIF is intended for debugging and is not to be used in ap‐
2781 plication programs.
2782 list_to_ref(String) -> reference()
2785 Types:
2787 String = string()
2789 Returns a reference whose text representation is a String, for
2791 example:
2792 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
2794 #Ref<0.4192537678.4073193475.71181>
2795 Failure: badarg if String contains a bad representation of a
2797 reference.
2798 Warning:
2800 This BIF is intended for debugging and is not to be used in ap‐
2801 plication programs.
2802 list_to_tuple(List) -> tuple()
2805 Types:
2807 List = [term()]
2809 Returns a tuple corresponding to List, for example
2811 > list_to_tuple([share, ['Ericsson_B', 163]]).
2813 {share, ['Ericsson_B', 163]}
2814 List can contain any Erlang terms.
2816 load_module(Module, Binary) -> {module, Module} | {error, Reason}
2818 Types:
2820 Module = module()
2822 Binary = binary()
2823 Reason = badfile | not_purged | on_load
2824 If Binary contains the object code for module Module, this BIF
2826 loads that object code. If the code for module Module already
2827 exists, all export references are replaced so they point to the
2828 newly loaded code. The previously loaded code is kept in the
2829 system as old code, as there can still be processes executing
2830 that code.
2831 Returns either {module, Module}, or {error, Reason} if loading
2833 fails. Reason is one of the following:
2834 badfile:
2836 The object code in Binary has an incorrect format or the ob‐
2837 ject code contains code for another module than Module.
2838 not_purged:
2840 Binary contains a module that cannot be loaded because old
2841 code for this module already exists.
2842 Warning:
2844 This BIF is intended for the code server (see code(3)) and is
2845 not to be used elsewhere.
2846 erlang:load_nif(Path, LoadInfo) -> ok | Error
2849 Types:
2851 Path = string()
2853 LoadInfo = term()
2854 Error = {error, {Reason, Text :: string()}}
2855 Reason =
2856 load_failed | bad_lib | load | reload | upgrade |
2857 old_code
2858 Loads and links a dynamic library containing native implemented
2860 functions (NIFs) for a module. Path is a file path to the share‐
2861 able object/dynamic library file minus the OS-dependent file ex‐
2862 tension (.so for Unix and .dll for Windows). Notice that on most
2863 OSs the library has to have a different name on disc when an up‐
2864 grade of the nif is done. If the name is the same, but the con‐
2865 tents differ, the old library may be loaded instead. For infor‐
2866 mation on how to implement a NIF library, see erl_nif(3).
2867 LoadInfo can be any term. It is passed on to the library as part
2869 of the initialization. A good practice is to include a module
2870 version number to support future code upgrade scenarios.
2871 The call to load_nif/2 must be made directly from the Erlang
2873 code of the module that the NIF library belongs to. It returns
2874 either ok, or {error,{Reason,Text}} if loading fails. Reason is
2875 one of the following atoms while Text is a human readable string
2876 that can give more information about the failure:
2877 load_failed:
2879 The OS failed to load the NIF library.
2880 bad_lib:
2882 The library did not fulfill the requirements as a NIF li‐
2883 brary of the calling module.
2884 load | upgrade:
2886 The corresponding library callback was unsuccessful.
2887 reload:
2889 A NIF library is already loaded for this module instance.
2890 The previously deprecated reload feature was removed in OTP
2891 20.
2892 old_code:
2894 The call to load_nif/2 was made from the old code of a mod‐
2895 ule that has been upgraded; this is not allowed.
2896 notsup:
2898 Lack of support. Such as loading NIF library for a HiPE com‐
2899 piled module.
2900 erlang:loaded() -> [Module]
2902 Types:
2904 Module = module()
2906 Returns a list of all loaded Erlang modules (current and old
2908 code), including preloaded modules.
2909 See also code(3).
2911 erlang:localtime() -> DateTime
2913 Types:
2915 DateTime = calendar:datetime()
2917 Returns the current local date and time, {{Year, Month, Day},
2919 {Hour, Minute, Second}}, for example:
2920 > erlang:localtime().
2922 {{1996,11,6},{14,45,17}}
2923 The time zone and Daylight Saving Time correction depend on the
2925 underlying OS.
2926 erlang:localtime_to_universaltime(Localtime) -> Universaltime
2928 Types:
2930 Localtime = Universaltime = calendar:datetime()
2932 Converts local date and time to Universal Time Coordinated
2934 (UTC), if supported by the underlying OS. Otherwise no conver‐
2935 sion is done and Localtime is returned. Example:
2936 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
2938 {{1996,11,6},{13,45,17}}
2939 Failure: badarg if Localtime denotes an invalid date and time.
2941 erlang:localtime_to_universaltime(Localtime, IsDst) ->
2943 Universaltime
2944 Types:
2946 Localtime = Universaltime = calendar:datetime()
2948 IsDst = true | false | undefined
2949 Converts local date and time to Universal Time Coordinated (UTC)
2951 as erlang:localtime_to_universaltime/1, but the caller decides
2952 if Daylight Saving Time is active.
2953 If IsDst == true, Localtime is during Daylight Saving Time, if
2955 IsDst == false it is not. If IsDst == undefined, the underlying
2956 OS can guess, which is the same as calling erlang:local‐
2957 time_to_universaltime(Localtime).
2958 Examples:
2960 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
2962 {{1996,11,6},{12,45,17}}
2963 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
2964 {{1996,11,6},{13,45,17}}
2965 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
2966 {{1996,11,6},{13,45,17}}
2967 Failure: badarg if Localtime denotes an invalid date and time.
2969 make_ref() -> reference()
2971 Returns a unique reference. The reference is unique among con‐
2973 nected nodes.
2974 Warning:
2976 Known issue: When a node is restarted multiple times with the
2977 same node name, references created on a newer node can be mis‐
2978 taken for a reference created on an older node with the same
2979 node name.
2980 erlang:make_tuple(Arity, InitialValue) -> tuple()
2983 Types:
2985 Arity = arity()
2987 InitialValue = term()
2988 Creates a new tuple of the specified Arity, where all elements
2990 are InitialValue, for example:
2991 > erlang:make_tuple(4, []).
2993 {[],[],[],[]}
2994 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
2996 Types:
2998 Arity = arity()
3000 DefaultValue = term()
3001 InitList = [{Position :: integer() >= 1, term()}]
3002 Creates a tuple of size Arity, where each element has value De‐
3004 faultValue, and then fills in values from InitList. Each list
3005 element in InitList must be a two-tuple, where the first element
3006 is a position in the newly created tuple and the second element
3007 is any term. If a position occurs more than once in the list,
3008 the term corresponding to the last occurrence is used. Example:
3009 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3011 {[],aa,[],[],zz}
3012 map_get(Key, Map) -> Value
3014 Types:
3016 Map = map()
3018 Key = Value = any()
3019 Returns value Value associated with Key if Map contains Key.
3021 The call fails with a {badmap,Map} exception if Map is not a
3023 map, or with a {badkey,Key} exception if no value is associated
3024 with Key.
3025 Example:
3027 > Key = 1337,
3029 Map = #{42 => value_two,1337 => "value one","a" => 1},
3030 map_get(Key,Map).
3031 "value one"
3032 Allowed in guard tests.
3034 map_size(Map) -> integer() >= 0
3036 Types:
3038 Map = map()
3040 Returns an integer, which is the number of key-value pairs in
3042 Map, for example:
3043 > map_size(#{a=>1, b=>2, c=>3}).
3045 3
3046 Allowed in guard tests.
3048 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3050 TestResult
3051 Types:
3053 MatchAgainst = [term()] | tuple()
3055 MatchSpec = term()
3056 Type = table | trace
3057 TestResult =
3058 {ok, term(), [return_trace], [{error | warning,
3059 string()}]} |
3060 {error, [{error | warning, string()}]}
3061 Tests a match specification used in calls to ets:select/2 and
3063 erlang:trace_pattern/3. The function tests both a match specifi‐
3064 cation for "syntactic" correctness and runs the match specifica‐
3065 tion against the object. If the match specification contains er‐
3066 rors, the tuple {error, Errors} is returned, where Errors is a
3067 list of natural language descriptions of what was wrong with the
3068 match specification.
3069 If Type is table, the object to match against is to be a tuple.
3071 The function then returns {ok,Result,[],Warnings}, where Result
3072 is what would have been the result in a real ets:select/2 call,
3073 or false if the match specification does not match the object
3074 tuple.
3075 If Type is trace, the object to match against is to be a list.
3077 The function returns {ok, Result, Flags, Warnings}, where Result
3078 is one of the following:
3079 * true if a trace message is to be emitted
3081 * false if a trace message is not to be emitted
3083 * The message term to be appended to the trace message
3085 Flags is a list containing all the trace flags to be enabled,
3087 currently this is only return_trace.
3088 This is a useful debugging and test tool, especially when writ‐
3090 ing complicated match specifications.
3091 See also ets:test_ms/2.
3093 max(Term1, Term2) -> Maximum
3095 Types:
3097 Term1 = Term2 = Maximum = term()
3099 Returns the largest of Term1 and Term2. If the terms are equal,
3101 Term1 is returned.
3102 erlang:md5(Data) -> Digest
3104 Types:
3106 Data = iodata()
3108 Digest = binary()
3109 Computes an MD5 message digest from Data, where the length of
3111 the digest is 128 bits (16 bytes). Data is a binary or a list of
3112 small integers and binaries.
3113 For more information about MD5, see RFC 1321 - The MD5 Message-
3115 Digest Algorithm.
3116 Warning:
3118 The MD5 Message-Digest Algorithm is not considered safe for
3119 code-signing or software-integrity purposes.
3120 erlang:md5_final(Context) -> Digest
3123 Types:
3125 Context = Digest = binary()
3127 Finishes the update of an MD5 Context and returns the computed
3129 MD5 message digest.
3130 erlang:md5_init() -> Context
3132 Types:
3134 Context = binary()
3136 Creates an MD5 context, to be used in the following calls to
3138 md5_update/2.
3139 erlang:md5_update(Context, Data) -> NewContext
3141 Types:
3143 Context = binary()
3145 Data = iodata()
3146 NewContext = binary()
3147 Update an MD5 Context with Data and returns a NewContext.
3149 erlang:memory() -> [{Type, Size}]
3151 Types:
3153 Type = memory_type()
3155 Size = integer() >= 0
3156 memory_type() =
3157 total | processes | processes_used | system | atom |
3158 atom_used | binary | code | ets
3159 Returns a list with information about memory dynamically allo‐
3161 cated by the Erlang emulator. Each list element is a tuple
3162 {Type, Size}. The first element Type is an atom describing mem‐
3163 ory type. The second element Size is the memory size in bytes.
3164 Memory types:
3166 total:
3168 The total amount of memory currently allocated. This is the
3169 same as the sum of the memory size for processes and system.
3170 processes:
3172 The total amount of memory currently allocated for the Er‐
3173 lang processes.
3174 processes_used:
3176 The total amount of memory currently used by the Erlang pro‐
3177 cesses. This is part of the memory presented as processes
3178 memory.
3179 system:
3181 The total amount of memory currently allocated for the emu‐
3182 lator that is not directly related to any Erlang process.
3183 Memory presented as processes is not included in this mem‐
3184 ory. instrument(3) can be used to get a more detailed break‐
3185 down of what memory is part of this type.
3186 atom:
3188 The total amount of memory currently allocated for atoms.
3189 This memory is part of the memory presented as system mem‐
3190 ory.
3191 atom_used:
3193 The total amount of memory currently used for atoms. This
3194 memory is part of the memory presented as atom memory.
3195 binary:
3197 The total amount of memory currently allocated for binaries.
3198 This memory is part of the memory presented as system mem‐
3199 ory.
3200 code:
3202 The total amount of memory currently allocated for Erlang
3203 code. This memory is part of the memory presented as system
3204 memory.
3205 ets:
3207 The total amount of memory currently allocated for ETS ta‐
3208 bles. This memory is part of the memory presented as system
3209 memory.
3210 low:
3212 Only on 64-bit halfword emulator. The total amount of memory
3213 allocated in low memory areas that are restricted to < 4 GB,
3214 although the system can have more memory.
3215 Can be removed in a future release of the halfword emulator.
3217 maximum:
3219 The maximum total amount of memory allocated since the emu‐
3220 lator was started. This tuple is only present when the emu‐
3221 lator is run with instrumentation.
3222 For information on how to run the emulator with instrumenta‐
3224 tion, see instrument(3) and/or erl(1).
3225 Note:
3227 The system value is not complete. Some allocated memory that is
3228 to be part of this value is not.
3229 When the emulator is run with instrumentation, the system value
3231 is more accurate, but memory directly allocated for malloc (and
3232 friends) is still not part of the system value. Direct calls to
3233 malloc are only done from OS-specific runtime libraries and per‐
3234 haps from user-implemented Erlang drivers that do not use the
3235 memory allocation functions in the driver interface.
3236 As the total value is the sum of processes and system, the error
3238 in system propagates to the total value.
3239 The different amounts of memory that are summed are not gathered
3241 atomically, which introduces an error in the result.
3242 The different values have the following relation to each other.
3245 Values beginning with an uppercase letter is not part of the re‐
3246 sult.
3247 total = processes + system
3249 processes = processes_used + ProcessesNotUsed
3250 system = atom + binary + code + ets + OtherSystem
3251 atom = atom_used + AtomNotUsed
3252 RealTotal = processes + RealSystem
3253 RealSystem = system + MissedSystem
3254 More tuples in the returned list can be added in a future re‐
3256 lease.
3257 Note:
3259 The total value is supposed to be the total amount of memory dy‐
3260 namically allocated by the emulator. Shared libraries, the code
3261 of the emulator itself, and the emulator stacks are not supposed
3262 to be included. That is, the total value is not supposed to be
3263 equal to the total size of all pages mapped to the emulator.
3264 Also, because of fragmentation and prereservation of memory ar‐
3266 eas, the size of the memory segments containing the dynamically
3267 allocated memory blocks can be much larger than the total size
3268 of the dynamically allocated memory blocks.
3269 Note:
3272 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
3273 loc(3) allocators are enabled (default behavior).
3274 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3277 erlang:memory(Type :: memory_type()) -> integer() >= 0
3279 erlang:memory(TypeList :: [memory_type()]) ->
3281 [{memory_type(), integer() >= 0}]
3282 Types:
3284 memory_type() =
3286 total | processes | processes_used | system | atom |
3287 atom_used | binary | code | ets
3288 Returns the memory size in bytes allocated for memory of type
3290 Type. The argument can also be specified as a list of mem‐
3291 ory_type() atoms, in which case a corresponding list of {mem‐
3292 ory_type(), Size :: integer >= 0} tuples is returned.
3293 Note:
3295 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
3296 loc(3) allocators are enabled (default behavior).
3297 Failures:
3300 badarg:
3302 If Type is not one of the memory types listed in the de‐
3303 scription of erlang:memory/0.
3304 badarg:
3306 If maximum is passed as Type and the emulator is not run in
3307 instrumented mode.
3308 notsup:
3310 If an erts_alloc(3) allocator has been disabled.
3311 See also erlang:memory/0.
3313 min(Term1, Term2) -> Minimum
3315 Types:
3317 Term1 = Term2 = Minimum = term()
3319 Returns the smallest of Term1 and Term2. If the terms are equal,
3321 Term1 is returned.
3322 module_loaded(Module) -> boolean()
3324 Types:
3326 Module = module()
3328 Returns true if the module Module is loaded, otherwise false. It
3330 does not attempt to load the module.
3331 Warning:
3333 This BIF is intended for the code server (see code(3)) and is
3334 not to be used elsewhere.
3335 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3338 MonitorRef
3339 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3341 MonitorRef
3342 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3344 Types:
3346 MonitorRef = reference()
3348 registered_name() = atom()
3349 registered_process_identifier() =
3350 registered_name() | {registered_name(), node()}
3351 monitor_process_identifier() =
3352 pid() | registered_process_identifier()
3353 monitor_port_identifier() = port() | registered_name()
3354 Sends a monitor request of type Type to the entity identified by
3356 Item. If the monitored entity does not exist or it changes moni‐
3357 tored state, the caller of monitor/2 is notified by a message on
3358 the following format:
3359 {Tag, MonitorRef, Type, Object, Info}
3361 Note:
3363 The monitor request is an asynchronous signal. That is, it takes
3364 time before the signal reaches its destination.
3365 Type can be one of the following atoms: process, port or
3368 time_offset.
3369 A process or port monitor is triggered only once, after that it
3371 is removed from both monitoring process and the monitored en‐
3372 tity. Monitors are fired when the monitored process or port ter‐
3373 minates, does not exist at the moment of creation, or if the
3374 connection to it is lost. If the connection to it is lost, we do
3375 not know if it still exists. The monitoring is also turned off
3376 when demonitor/1 is called.
3377 A process or port monitor by name resolves the RegisteredName to
3379 pid() or port() only once at the moment of monitor instantia‐
3380 tion, later changes to the name registration will not affect the
3381 existing monitor.
3382 When a process or port monitor is triggered, a 'DOWN' message is
3384 sent that has the following pattern:
3385 {'DOWN', MonitorRef, Type, Object, Info}
3387 In the monitor message MonitorRef and Type are the same as de‐
3389 scribed earlier, and:
3390 Object:
3392 The monitored entity, which triggered the event. When moni‐
3393 toring a local process or port, Object will be equal to the
3394 pid() or port() that was being monitored. When monitoring
3395 process or port by name, Object will have format {Regis‐
3396 teredName, Node} where RegisteredName is the name which has
3397 been used with monitor/2 call and Node is local or remote
3398 node name (for ports monitored by name, Node is always local
3399 node name).
3400 Info:
3402 Either the exit reason of the process, noproc (process or
3403 port did not exist at the time of monitor creation), or no‐
3404 connection (no connection to the node where the monitored
3405 process resides).
3406 Monitoring a process:
3408 Creates monitor between the current process and another
3409 process identified by Item, which can be a pid() (local or
3410 remote), an atom RegisteredName or a tuple {RegisteredName,
3411 Node} for a registered process, located elsewhere.
3412 Note:
3414 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3415 with badarg if the monitored process resided on a primitive
3416 node (such as erl_interface or jinterface), where remote
3417 process monitoring is not implemented.
3418 Now, such a call to monitor will instead succeed and a monitor
3420 is created. But the monitor will only supervise the connec‐
3421 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3422 only message that may be received, as the primitive node have
3423 no way of reporting the status of the monitored process.
3424 Monitoring a port:
3427 Creates monitor between the current process and a port iden‐
3428 tified by Item, which can be a port() (only local), an atom
3429 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3430 istered port, located on this node. Note, that attempt to
3431 monitor a remote port will result in badarg.
3432 Monitoring a time_offset:
3434 Monitors changes in time offset between Erlang monotonic
3435 time and Erlang system time. One valid Item exists in combi‐
3436 nation with the time_offset Type, namely the atom clock_ser‐
3437 vice. Notice that the atom clock_service is not the regis‐
3438 tered name of a process. In this case it serves as an iden‐
3439 tifier of the runtime system internal clock service at cur‐
3440 rent runtime system instance.
3441 The monitor is triggered when the time offset is changed.
3443 This either if the time offset value is changed, or if the
3444 offset is changed from preliminary to final during finaliza‐
3445 tion of the time offset when the single time warp mode is
3446 used. When a change from preliminary to final time offset is
3447 made, the monitor is triggered once regardless of whether
3448 the time offset value was changed or not.
3449 If the runtime system is in multi time warp mode, the time
3451 offset is changed when the runtime system detects that the
3452 OS system time has changed. The runtime system does, how‐
3453 ever, not detect this immediately when it occurs. A task
3454 checking the time offset is scheduled to execute at least
3455 once a minute, so under normal operation this is to be de‐
3456 tected within a minute, but during heavy load it can take
3457 longer time.
3458 The monitor is not automatically removed after it has been
3460 triggered. That is, repeated changes of the time offset
3461 trigger the monitor repeatedly.
3462 When the monitor is triggered a 'CHANGE' message is sent to
3464 the monitoring process. A 'CHANGE' message has the following
3465 pattern:
3466 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3468 where MonitorRef, Type, and Item are the same as described
3470 above, and NewTimeOffset is the new time offset.
3471 When the 'CHANGE' message has been received you are guaran‐
3473 teed not to retrieve the old time offset when calling er‐
3474 lang:time_offset(). Notice that you can observe the change
3475 of the time offset when calling erlang:time_offset() before
3476 you get the 'CHANGE' message.
3477 Making several calls to monitor/2 for the same Item and/or Type
3479 is not an error; it results in as many independent monitoring
3480 instances.
3481 The monitor functionality is expected to be extended. That is,
3483 other Types and Items are expected to be supported in a future
3484 release.
3485 Note:
3487 If or when monitor/2 is extended, other possible values for Tag,
3488 Object, and Info in the monitor message will be introduced.
3489 monitor_node(Node, Flag) -> true
3492 Types:
3494 Node = node()
3496 Flag = boolean()
3497 Monitor the status of the node Node. If Flag is true, monitoring
3499 is turned on. If Flag is false, monitoring is turned off.
3500 Making several calls to monitor_node(Node, true) for the same
3502 Node is not an error; it results in as many independent monitor‐
3503 ing instances.
3504 If Node fails or does not exist, the message {nodedown, Node} is
3506 delivered to the process. If a process has made two calls to
3507 monitor_node(Node, true) and Node terminates, two nodedown mes‐
3508 sages are delivered to the process. If there is no connection to
3509 Node, an attempt is made to create one. If this fails, a node‐
3510 down message is delivered.
3511 Nodes connected through hidden connections can be monitored as
3513 any other nodes.
3514 Failure: badarg if the local node is not alive.
3516 erlang:monitor_node(Node, Flag, Options) -> true
3518 Types:
3520 Node = node()
3522 Flag = boolean()
3523 Options = [Option]
3524 Option = allow_passive_connect
3525 Behaves as monitor_node/2 except that it allows an extra option
3527 to be specified, namely allow_passive_connect. This option al‐
3528 lows the BIF to wait the normal network connection time-out for
3529 the monitored node to connect itself, even if it cannot be ac‐
3530 tively connected from this node (that is, it is blocked). The
3531 state where this can be useful can only be achieved by using the
3532 Kernel option dist_auto_connect once. If that option is not
3533 used, option allow_passive_connect has no effect.
3534 Note:
3536 Option allow_passive_connect is used internally and is seldom
3537 needed in applications where the network topology and the Kernel
3538 options in effect are known in advance.
3539 Failure: badarg if the local node is not alive or the option
3542 list is malformed.
3543 erlang:monotonic_time() -> integer()
3545 Returns the current Erlang monotonic time in native time unit.
3547 This is a monotonically increasing time since some unspecified
3548 point in time.
3549 Note:
3551 This is a monotonically increasing time, but not a strictly
3552 monotonically increasing time. That is, consecutive calls to er‐
3553 lang:monotonic_time/0 can produce the same result.
3554 Different runtime system instances will use different unspeci‐
3556 fied points in time as base for their Erlang monotonic clocks.
3557 That is, it is pointless comparing monotonic times from differ‐
3558 ent runtime system instances. Different runtime system instances
3559 can also place this unspecified point in time different relative
3560 runtime system start. It can be placed in the future (time at
3561 start is a negative value), the past (time at start is a posi‐
3562 tive value), or the runtime system start (time at start is
3563 zero). The monotonic time at runtime system start can be re‐
3564 trieved by calling erlang:system_info(start_time).
3565 erlang:monotonic_time(Unit) -> integer()
3568 Types:
3570 Unit = time_unit()
3572 Returns the current Erlang monotonic time converted into the
3574 Unit passed as argument.
3575 Same as calling erlang:convert_time_unit(erlang:mono‐
3577 tonic_time(), native, Unit), however optimized for commonly used
3578 Units.
3579 erlang:nif_error(Reason) -> no_return()
3581 Types:
3583 Reason = term()
3585 Works exactly like error/1, but Dialyzer thinks that this BIF
3587 will return an arbitrary term. When used in a stub function for
3588 a NIF to generate an exception when the NIF library is not
3589 loaded, Dialyzer does not generate false warnings.
3590 erlang:nif_error(Reason, Args) -> no_return()
3592 Types:
3594 Reason = term()
3596 Args = [term()]
3597 Works exactly like error/2, but Dialyzer thinks that this BIF
3599 will return an arbitrary term. When used in a stub function for
3600 a NIF to generate an exception when the NIF library is not
3601 loaded, Dialyzer does not generate false warnings.
3602 node() -> Node
3604 Types:
3606 Node = node()
3608 Returns the name of the local node. If the node is not alive,
3610 nonode@nohost is returned instead.
3611 Allowed in guard tests.
3613 node(Arg) -> Node
3615 Types:
3617 Arg = pid() | port() | reference()
3619 Node = node()
3620 Returns the node where Arg originates. Arg can be a process
3622 identifier, a reference, or a port. If the local node is not
3623 alive, nonode@nohost is returned.
3624 Allowed in guard tests.
3626 nodes() -> Nodes
3628 Types:
3630 Nodes = [node()]
3632 Returns a list of all visible nodes in the system, except the
3634 local node. Same as nodes(visible).
3635 nodes(Arg) -> Nodes
3637 Types:
3639 Arg = NodeType | [NodeType]
3641 NodeType = visible | hidden | connected | this | known
3642 Nodes = [node()]
3643 Returns a list of nodes according to the argument specified. The
3645 returned result, when the argument is a list, is the list of
3646 nodes satisfying the disjunction(s) of the list elements.
3647 NodeTypes:
3649 visible:
3651 Nodes connected to this node through normal connections.
3652 hidden:
3654 Nodes connected to this node through hidden connections.
3655 connected:
3657 All nodes connected to this node.
3658 this:
3660 This node.
3661 known:
3663 Nodes that are known to this node. That is, connected nodes
3664 and nodes referred to by process identifiers, port identi‐
3665 fiers, and references located on this node. The set of known
3666 nodes is garbage collected. Notice that this garbage collec‐
3667 tion can be delayed. For more information, see erlang:sys‐
3668 tem_info(delayed_node_table_gc).
3669 Some equalities: [node()] = nodes(this), nodes(connected) =
3671 nodes([visible, hidden]), and nodes() = nodes(visible).
3672 now() -> Timestamp
3674 Types:
3676 Timestamp = timestamp()
3678 timestamp() =
3679 {MegaSecs :: integer() >= 0,
3680 Secs :: integer() >= 0,
3681 MicroSecs :: integer() >= 0}
3682 Warning:
3684 This function is deprecated. Do not use it.
3685 For more information, see section Time and Time Correction in
3687 the User's Guide. Specifically, section Dos and Dont's de‐
3688 scribes what to use instead of erlang:now/0.
3689 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
3692 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
3693 provided by the underlying OS. Otherwise some other point in
3694 time is chosen. It is also guaranteed that the following calls
3695 to this BIF return continuously increasing values. Hence, the
3696 return value from erlang:now/0 can be used to generate unique
3697 time stamps. If it is called in a tight loop on a fast machine,
3698 the time of the node can become skewed.
3699 Can only be used to check the local time of day if the time-zone
3701 information of the underlying OS is properly configured.
3702 open_port(PortName, PortSettings) -> port()
3704 Types:
3706 PortName =
3708 {spawn, Command :: string() | binary()} |
3709 {spawn_driver, Command :: string() | binary()} |
3710 {spawn_executable, FileName :: file:name_all()} |
3711 {fd, In :: integer() >= 0, Out :: integer() >= 0}
3712 PortSettings = [Opt]
3713 Opt =
3714 {packet, N :: 1 | 2 | 4} |
3715 stream |
3716 {line, L :: integer() >= 0} |
3717 {cd, Dir :: string() | binary()} |
3718 {env,
3719 Env ::
3720 [{Name :: os:env_var_name(),
3721 Val :: os:env_var_value() | false}]} |
3722 {args, [string() | binary()]} |
3723 {arg0, string() | binary()} |
3724 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
3725 |
3726 in | out | binary | eof |
3727 {parallelism, Boolean :: boolean()} |
3728 hide |
3729 {busy_limits_port,
3730 {integer() >= 0, integer() >= 0} | disabled} |
3731 {busy_limits_msgq,
3732 {integer() >= 0, integer() >= 0} | disabled}
3733 Returns a port identifier as the result of opening a new Erlang
3735 port. A port can be seen as an external Erlang process.
3736 The name of the executable as well as the arguments specifed in
3738 cd, env, args, and arg0 are subject to Unicode filename transla‐
3739 tion if the system is running in Unicode filename mode. To avoid
3740 translation or to force, for example UTF-8, supply the exe‐
3741 cutable and/or arguments as a binary in the correct encoding.
3742 For details, see the module file(3), the function file:na‐
3743 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
3744 User's Guide.
3745 Note:
3747 The characters in the name (if specified as a list) can only be
3748 > 255 if the Erlang virtual machine is started in Unicode file‐
3749 name translation mode. Otherwise the name of the executable is
3750 limited to the ISO Latin-1 character set.
3751 PortNames:
3754 {spawn, Command}:
3756 Starts an external program. Command is the name of the ex‐
3757 ternal program to be run. Command runs outside the Erlang
3758 work space unless an Erlang driver with the name Command is
3759 found. If found, that driver is started. A driver runs in
3760 the Erlang work space, which means that it is linked with
3761 the Erlang runtime system.
3762 For external programs, PATH is searched (or an equivalent
3764 method is used to find programs, depending on the OS). This
3765 is done by invoking the shell on certain platforms. The
3766 first space-separated token of the command is considered as
3767 the name of the executable (or driver). This (among other
3768 things) makes this option unsuitable for running programs
3769 with spaces in filenames or directory names. If spaces in
3770 executable filenames are desired, use {spawn_executable,
3771 Command} instead.
3772 {spawn_driver, Command}:
3774 Works like {spawn, Command}, but demands the first (space-
3775 separated) token of the command to be the name of a loaded
3776 driver. If no driver with that name is loaded, a badarg er‐
3777 ror is raised.
3778 {spawn_executable, FileName}:
3780 Works like {spawn, FileName}, but only runs external exe‐
3781 cutables. FileName in its whole is used as the name of the
3782 executable, including any spaces. If arguments are to be
3783 passed, the PortSettings args and arg0 can be used.
3784 The shell is usually not invoked to start the program, it is
3786 executed directly. PATH (or equivalent) is not searched. To
3787 find a program in PATH to execute, use os:find_executable/1.
3788 Only if a shell script or .bat file is executed, the appro‐
3790 priate command interpreter is invoked implicitly, but there
3791 is still no command-argument expansion or implicit PATH
3792 search.
3793 If FileName cannot be run, an error exception is raised,
3795 with the POSIX error code as the reason. The error reason
3796 can differ between OSs. Typically the error enoent is raised
3797 when an attempt is made to run a program that is not found
3798 and eacces is raised when the specified file is not exe‐
3799 cutable.
3800 {fd, In, Out}:
3802 Allows an Erlang process to access any currently opened file
3803 descriptors used by Erlang. The file descriptor In can be
3804 used for standard input, and the file descriptor Out for
3805 standard output. It is only used for various servers in the
3806 Erlang OS (shell and user). Hence, its use is limited.
3807 PortSettings is a list of settings for the port. The valid set‐
3809 tings are as follows:
3810 {packet, N}:
3812 Messages are preceded by their length, sent in N bytes, with
3813 the most significant byte first. The valid values for N are
3814 1, 2, and 4.
3815 stream:
3817 Output messages are sent without packet lengths. A user-de‐
3818 fined protocol must be used between the Erlang process and
3819 the external object.
3820 {line, L}:
3822 Messages are delivered on a per line basis. Each line (de‐
3823 limited by the OS-dependent newline sequence) is delivered
3824 in a single message. The message data format is {Flag,
3825 Line}, where Flag is eol or noeol, and Line is the data de‐
3826 livered (without the newline sequence).
3827 L specifies the maximum line length in bytes. Lines longer
3829 than this are delivered in more than one message, with Flag
3830 set to noeol for all but the last message. If end of file is
3831 encountered anywhere else than immediately following a new‐
3832 line sequence, the last line is also delivered with Flag set
3833 to noeol. Otherwise lines are delivered with Flag set to
3834 eol.
3835 The {packet, N} and {line, L} settings are mutually exclu‐
3837 sive.
3838 {cd, Dir}:
3840 Only valid for {spawn, Command} and {spawn_executable, File‐
3841 Name}. The external program starts using Dir as its working
3842 directory. Dir must be a string.
3843 {env, Env}:
3845 Types:
3846 Name = os:env_var_name()
3847 Val = os:env_var_value() | false
3848 Env = [{Name, Val}]
3849 Only valid for {spawn, Command}, and {spawn_executable,
3851 FileName}. The environment of the started process is ex‐
3852 tended using the environment specifications in Env.
3853 Env is to be a list of tuples {Name, Val}, where Name is the
3855 name of an environment variable, and Val is the value it is
3856 to have in the spawned port process. Both Name and Val must
3857 be strings. The one exception is Val being the atom false
3858 (in analogy with os:getenv/1, which removes the environment
3859 variable.
3860 For information about encoding requirements, see documenta‐
3862 tion of the types for Name and Val.
3863 {args, [ string() | binary() ]}:
3865 Only valid for {spawn_executable, FileName} and specifies
3866 arguments to the executable. Each argument is specified as a
3867 separate string and (on Unix) eventually ends up as one ele‐
3868 ment each in the argument vector. On other platforms, a sim‐
3869 ilar behavior is mimicked.
3870 The arguments are not expanded by the shell before they are
3872 supplied to the executable. Most notably this means that
3873 file wildcard expansion does not occur. To expand wildcards
3874 for the arguments, use filelib:wildcard/1. Notice that even
3875 if the program is a Unix shell script, meaning that the
3876 shell ultimately is invoked, wildcard expansion does not oc‐
3877 cur, and the script is provided with the untouched argu‐
3878 ments. On Windows, wildcard expansion is always up to the
3879 program itself, therefore this is not an issue.
3880 The executable name (also known as argv[0]) is not to be
3882 specified in this list. The proper executable name is auto‐
3883 matically used as argv[0], where applicable.
3884 If you explicitly want to set the program name in the argu‐
3886 ment vector, option arg0 can be used.
3887 {arg0, string() | binary()}:
3889 Only valid for {spawn_executable, FileName} and explicitly
3890 specifies the program name argument when running an exe‐
3891 cutable. This can in some circumstances, on some OSs, be de‐
3892 sirable. How the program responds to this is highly system-
3893 dependent and no specific effect is guaranteed.
3894 exit_status:
3896 Only valid for {spawn, Command}, where Command refers to an
3897 external program, and for {spawn_executable, FileName}.
3898 When the external process connected to the port exits, a
3900 message of the form {Port,{exit_status,Status}} is sent to
3901 the connected process, where Status is the exit status of
3902 the external process. If the program aborts on Unix, the
3903 same convention is used as the shells do (that is, 128+sig‐
3904 nal).
3905 If option eof is specified also, the messages eof and
3907 exit_status appear in an unspecified order.
3908 If the port program closes its stdout without exiting, op‐
3910 tion exit_status does not work.
3911 use_stdio:
3913 Only valid for {spawn, Command} and {spawn_executable, File‐
3914 Name}. It allows the standard input and output (file de‐
3915 scriptors 0 and 1) of the spawned (Unix) process for commu‐
3916 nication with Erlang.
3917 nouse_stdio:
3919 The opposite of use_stdio. It uses file descriptors 3 and 4
3920 for communication with Erlang.
3921 stderr_to_stdout:
3923 Affects ports to external programs. The executed program
3924 gets its standard error file redirected to its standard out‐
3925 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
3926 clusive.
3927 overlapped_io:
3929 Affects ports to external programs on Windows only. The
3930 standard input and standard output handles of the port pro‐
3931 gram are, if this option is supplied, opened with flag
3932 FILE_FLAG_OVERLAPPED, so that the port program can (and
3933 must) do overlapped I/O on its standard handles. This is not
3934 normally the case for simple port programs, but an option of
3935 value for the experienced Windows programmer. On all other
3936 platforms, this option is silently discarded.
3937 in:
3939 The port can only be used for input.
3940 out:
3942 The port can only be used for output.
3943 binary:
3945 All I/O from the port is binary data objects as opposed to
3946 lists of bytes.
3947 eof:
3949 The port is not closed at the end of the file and does not
3950 produce an exit signal. Instead, it remains open and a
3951 {Port, eof} message is sent to the process holding the port.
3952 hide:
3954 When running on Windows, suppresses creation of a new con‐
3955 sole window when spawning the port program. (This option has
3956 no effect on other platforms.)
3957 {parallelism, Boolean}:
3959 Sets scheduler hint for port parallelism. If set to true,
3962 the virtual machine schedules port tasks; when doing so, it
3963 improves parallelism in the system. If set to false, the
3964 virtual machine tries to perform port tasks immediately, im‐
3965 proving latency at the expense of parallelism. The default
3966 can be set at system startup by passing command-line argu‐
3967 ment +spp to erl(1).
3968 {busy_limits_port, {Low, High} | disabled}:
3970 Sets limits that will be used for controlling the busy state
3971 of the port.
3972 When the ports internal output queue size becomes larger
3974 than or equal to High bytes, it enters the busy state. When
3975 it becomes less than Low bytes it leaves the busy state.
3976 When the port is in the busy state, processes sending com‐
3977 mands to it will be suspended until the port leaves the busy
3978 state. Commands are in this context either Port ! {Owner,
3979 {command, Data}} or port_command/[2,3].
3980 The Low limit is automatically adjusted to the same as High
3982 if it is set larger then High. Valid range of values for Low
3983 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
3984 If the atom disabled is passed, the port will never enter
3985 the busy state.
3986 The defaults are Low = 4096 and High = 8192.
3988 Note that this option is only valid when spawning an exe‐
3990 cutable (port program) by opening the spawn driver and when
3991 opening the fd driver. This option will cause a failure with
3992 a badarg exception when opening other drivers.
3993 {busy_limits_msgq, {Low, High} | disabled}:
3995 Sets limits that will be used for controlling the busy state
3996 of the port message queue.
3997 When the ports message queue size becomes larger than or
3999 equal to High bytes it enters the busy state. When it be‐
4000 comes less than Low bytes it leaves the busy state. When the
4001 port message queue is in the busy state, processes sending
4002 commands to it will be suspended until the port message
4003 queue leaves the busy state. Commands are in this context
4004 either Port ! {Owner, {command, Data}} or port_com‐
4005 mand/[2,3].
4006 The Low limit is automatically adjusted to the same as High
4008 if it is set larger then High. Valid range of values for Low
4009 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4010 If the atom disabled is passed, the port message queue will
4011 never enter the busy state.
4012 Note that if the driver statically has disabled the use of
4014 this feature, a failure with a badarg exception will be
4015 raised unless this option also is set to disable or not
4016 passed at all.
4017 The defaults are Low = 4096 and High = 8192 unless the
4019 driver itself does modifications of these values.
4020 Note that the driver might fail if it also adjust these lim‐
4022 its by itself and you have disabled this feature.
4023 The spawn driver (used when spawning an executable) and the
4025 fd driver do not disable this feature and do not adjust
4026 these limits by themselves.
4027 For more information see the documentation
4029 erl_drv_busy_msgq_limits().
4030 Default is stream for all port types and use_stdio for spawned
4032 ports.
4033 Failure: if the port cannot be opened, the exit reason is
4035 badarg, system_limit, or the POSIX error code that most closely
4036 describes the error, or einval if no POSIX code is appropriate:
4037 badarg:
4039 Bad input arguments to open_port.
4040 system_limit:
4042 All available ports in the Erlang emulator are in use.
4043 enomem:
4045 Not enough memory to create the port.
4046 eagain:
4048 No more available OS processes.
4049 enametoolong:
4051 Too long external command.
4052 emfile:
4054 No more available file descriptors (for the OS process that
4055 the Erlang emulator runs in).
4056 enfile:
4058 Full file table (for the entire OS).
4059 eacces:
4061 Command specified in {spawn_executable, Command} does not
4062 point out an executable file.
4063 enoent:
4065 FileName specified in {spawn_executable, FileName} does not
4066 point out an existing file.
4067 During use of a port opened using {spawn, Name}, {spawn_driver,
4069 Name}, or {spawn_executable, Name}, errors arising when sending
4070 messages to it are reported to the owning process using signals
4071 of the form {'EXIT', Port, PosixCode}. For the possible values
4072 of PosixCode, see file(3).
4073 The maximum number of ports that can be open at the same time
4075 can be configured by passing command-line flag +Q to erl(1).
4076 erlang:phash(Term, Range) -> Hash
4078 Types:
4080 Term = term()
4082 Range = Hash = integer() >= 1
4083 Range = 1..2^32, Hash = 1..Range
4084 Portable hash function that gives the same hash for the same Er‐
4086 lang term regardless of machine architecture and ERTS version
4087 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
4088 hash value for Term within the range 1..Range. The maximum value
4089 for Range is 2^32.
4090 erlang:phash2(Term) -> Hash
4092 erlang:phash2(Term, Range) -> Hash
4094 Types:
4096 Term = term()
4098 Range = integer() >= 1
4099 1..2^32
4100 Hash = integer() >= 0
4101 0..Range-1
4102 Portable hash function that gives the same hash for the same Er‐
4104 lang term regardless of machine architecture and ERTS version
4105 (the BIF was introduced in ERTS 5.2). The function returns a
4106 hash value for Term within the range 0..Range-1. The maximum
4107 value for Range is 2^32. When without argument Range, a value in
4108 the range 0..2^27-1 is returned.
4109 This BIF is always to be used for hashing terms. It distributes
4111 small integers better than phash/2, and it is faster for bignums
4112 and binaries.
4113 Notice that the range 0..Range-1 is different from the range of
4115 phash/2, which is 1..Range.
4116 pid_to_list(Pid) -> string()
4118 Types:
4120 Pid = pid()
4122 Returns a string corresponding to the text representation of
4124 Pid.
4125 erlang:port_call(Port, Operation, Data) -> term()
4127 Types:
4129 Port = port() | atom()
4131 Operation = integer()
4132 Data = term()
4133 Performs a synchronous call to a port. The meaning of Operation
4135 and Data depends on the port, that is, on the port driver. Not
4136 all port drivers support this feature.
4137 Port is a port identifier, referring to a driver.
4139 Operation is an integer, which is passed on to the driver.
4141 Data is any Erlang term. This data is converted to binary term
4143 format and sent to the port.
4144 Returns a term from the driver. The meaning of the returned data
4146 also depends on the port driver.
4147 Failures:
4149 badarg:
4151 If Port is not an identifier of an open port, or the regis‐
4152 tered name of an open port. If the calling process was pre‐
4153 viously linked to the closed port, identified by Port, the
4154 exit signal from the port is guaranteed to be delivered be‐
4155 fore this badarg exception occurs.
4156 badarg:
4158 If Operation does not fit in a 32-bit integer.
4159 badarg:
4161 If the port driver does not support synchronous control op‐
4162 erations.
4163 badarg:
4165 If the port driver so decides for any reason (probably some‐
4166 thing wrong with Operation or Data).
4167 Warning:
4169 Do not call port_call with an unknown Port identifier and ex‐
4170 pect badarg exception. Any undefined behavior is possible (in‐
4171 cluding node crash) depending on how the port driver inter‐
4172 prets the supplied arguments.
4173 port_close(Port) -> true
4176 Types:
4178 Port = port() | atom()
4180 Closes an open port. Roughly the same as Port ! {self(), close}
4182 except for the error behavior (see below), being synchronous,
4183 and that the port does not reply with {Port, closed}. Any
4184 process can close a port with port_close/1, not only the port
4185 owner (the connected process). If the calling process is linked
4186 to the port identified by Port, the exit signal from the port is
4187 guaranteed to be delivered before port_close/1 returns.
4188 For comparison: Port ! {self(), close} only fails with badarg if
4190 Port does not refer to a port or a process. If Port is a closed
4191 port, nothing happens. If Port is an open port and the calling
4192 process is the port owner, the port replies with {Port, closed}
4193 when all buffers have been flushed and the port really closes.
4194 If the calling process is not the port owner, the port owner
4195 fails with badsig.
4196 Notice that any process can close a port using Port ! {Por‐
4198 tOwner, close} as if it itself was the port owner, but the reply
4199 always goes to the port owner.
4200 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4202 chronous. Notice that this operation has always been documented
4203 as an asynchronous operation, while the underlying implementa‐
4204 tion has been synchronous. port_close/1 is however still fully
4205 synchronous because of its error behavior.
4206 Failure: badarg if Port is not an identifier of an open port, or
4208 the registered name of an open port. If the calling process was
4209 previously linked to the closed port, identified by Port, the
4210 exit signal from the port is guaranteed to be delivered before
4211 this badarg exception occurs.
4212 port_command(Port, Data) -> true
4214 Types:
4216 Port = port() | atom()
4218 Data = iodata()
4219 Sends data to a port. Same as Port ! {PortOwner, {command,
4221 Data}} except for the error behavior and being synchronous (see
4222 below). Any process can send data to a port with port_command/2,
4223 not only the port owner (the connected process).
4224 For comparison: Port ! {PortOwner, {command, Data}} only fails
4226 with badarg if Port does not refer to a port or a process. If
4227 Port is a closed port, the data message disappears without a
4228 sound. If Port is open and the calling process is not the port
4229 owner, the port owner fails with badsig. The port owner fails
4230 with badsig also if Data is an invalid I/O list.
4231 Notice that any process can send to a port using Port ! {Por‐
4233 tOwner, {command, Data}} as if it itself was the port owner.
4234 If the port is busy, the calling process is suspended until the
4236 port is not busy any more.
4237 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4239 truly asynchronous. Notice that this operation has always been
4240 documented as an asynchronous operation, while the underlying
4241 implementation has been synchronous. port_command/2 is however
4242 still fully synchronous because of its error behavior.
4243 Failures:
4245 badarg:
4247 If Port is not an identifier of an open port, or the regis‐
4248 tered name of an open port. If the calling process was pre‐
4249 viously linked to the closed port, identified by Port, the
4250 exit signal from the port is guaranteed to be delivered be‐
4251 fore this badarg exception occurs.
4252 badarg:
4254 If Data is an invalid I/O list.
4255 Warning:
4257 Do not send data to an unknown port. Any undefined behavior is
4258 possible (including node crash) depending on how the port driver
4259 interprets the data.
4260 port_command(Port, Data, OptionList) -> boolean()
4263 Types:
4265 Port = port() | atom()
4267 Data = iodata()
4268 Option = force | nosuspend
4269 OptionList = [Option]
4270 Sends data to a port. port_command(Port, Data, []) equals
4272 port_command(Port, Data).
4273 If the port command is aborted, false is returned, otherwise
4275 true.
4276 If the port is busy, the calling process is suspended until the
4278 port is not busy anymore.
4279 Options:
4281 force:
4283 The calling process is not suspended if the port is busy,
4284 instead the port command is forced through. The call fails
4285 with a notsup exception if the driver of the port does not
4286 support this. For more information, see driver flag
4287 ERL_DRV_FLAG_SOFT_BUSY.
4288 nosuspend:
4290 The calling process is not suspended if the port is busy,
4291 instead the port command is aborted and false is returned.
4292 Note:
4294 More options can be added in a future release.
4295 Failures:
4298 badarg:
4300 If Port is not an identifier of an open port, or the regis‐
4301 tered name of an open port. If the calling process was pre‐
4302 viously linked to the closed port, identified by Port, the
4303 exit signal from the port is guaranteed to be delivered be‐
4304 fore this badarg exception occurs.
4305 badarg:
4307 If Data is an invalid I/O list.
4308 badarg:
4310 If OptionList is an invalid option list.
4311 notsup:
4313 If option force has been passed, but the driver of the port
4314 does not allow forcing through a busy port.
4315 Warning:
4317 Do not send data to an unknown port. Any undefined behavior is
4318 possible (including node crash) depending on how the port driver
4319 interprets the data.
4320 port_connect(Port, Pid) -> true
4323 Types:
4325 Port = port() | atom()
4327 Pid = pid()
4328 Sets the port owner (the connected port) to Pid. Roughly the
4330 same as Port ! {Owner, {connect, Pid}} except for the following:
4331 * The error behavior differs, see below.
4333 * The port does not reply with {Port,connected}.
4335 * port_connect/1 is synchronous, see below.
4337 * The new port owner gets linked to the port.
4339 The old port owner stays linked to the port and must call un‐
4341 link(Port) if this is not desired. Any process can set the port
4342 owner to be any process with port_connect/2.
4343 For comparison: Port ! {self(), {connect, Pid}} only fails with
4345 badarg if Port does not refer to a port or a process. If Port is
4346 a closed port, nothing happens. If Port is an open port and the
4347 calling process is the port owner, the port replies with {Port,
4348 connected} to the old port owner. Notice that the old port owner
4349 is still linked to the port, while the new is not. If Port is an
4350 open port and the calling process is not the port owner, the
4351 port owner fails with badsig. The port owner fails with badsig
4352 also if Pid is not an existing local process identifier.
4353 Notice that any process can set the port owner using Port !
4355 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4356 but the reply always goes to the port owner.
4357 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4359 truly asynchronous. Notice that this operation has always been
4360 documented as an asynchronous operation, while the underlying
4361 implementation has been synchronous. port_connect/2 is however
4362 still fully synchronous because of its error behavior.
4363 Failures:
4365 badarg:
4367 If Port is not an identifier of an open port, or the regis‐
4368 tered name of an open port. If the calling process was pre‐
4369 viously linked to the closed port, identified by Port, the
4370 exit signal from the port is guaranteed to be delivered be‐
4371 fore this badarg exception occurs.
4372 badarg:
4374 If the process identified by Pid is not an existing local
4375 process.
4376 port_control(Port, Operation, Data) -> iodata() | binary()
4378 Types:
4380 Port = port() | atom()
4382 Operation = integer()
4383 Data = iodata()
4384 Performs a synchronous control operation on a port. The meaning
4386 of Operation and Data depends on the port, that is, on the port
4387 driver. Not all port drivers support this control feature.
4388 Returns a list of integers in the range 0..255, or a binary, de‐
4390 pending on the port driver. The meaning of the returned data
4391 also depends on the port driver.
4392 Failures:
4394 badarg:
4396 If Port is not an open port or the registered name of an
4397 open port.
4398 badarg:
4400 If Operation cannot fit in a 32-bit integer.
4401 badarg:
4403 If the port driver does not support synchronous control op‐
4404 erations.
4405 badarg:
4407 If the port driver so decides for any reason (probably
4408 something wrong with Operation or Data).
4409 Warning:
4411 Do not call port_control/3 with an unknown Port identifier and
4412 expect badarg exception. Any undefined behavior is possible
4413 (including node crash) depending on how the port driver inter‐
4414 prets the supplied arguments.
4415 erlang:port_info(Port) -> Result
4418 Types:
4420 Port = port() | atom()
4422 ResultItem =
4423 {registered_name, RegisteredName :: atom()} |
4424 {id, Index :: integer() >= 0} |
4425 {connected, Pid :: pid()} |
4426 {links, Pids :: [pid()]} |
4427 {name, String :: string()} |
4428 {input, Bytes :: integer() >= 0} |
4429 {output, Bytes :: integer() >= 0} |
4430 {os_pid, OsPid :: integer() >= 0 | undefined}
4431 Result = [ResultItem] | undefined
4432 Returns a list containing tuples with information about Port, or
4434 undefined if the port is not open. The order of the tuples is
4435 undefined, and all the tuples are not mandatory. If the port is
4436 closed and the calling process was previously linked to the
4437 port, the exit signal from the port is guaranteed to be deliv‐
4438 ered before port_info/1 returns undefined.
4439 The result contains information about the following Items:
4441 * registered_name (if the port has a registered name)
4443 * id
4445 * connected
4447 * links
4449 * name
4451 * input
4453 * output
4455 For more information about the different Items, see port_info/2.
4457 Failure: badarg if Port is not a local port identifier, or an
4459 atom.
4460 erlang:port_info(Port, Item :: connected) ->
4462 {connected, Pid} | undefined
4463 Types:
4465 Port = port() | atom()
4467 Pid = pid()
4468 Pid is the process identifier of the process connected to the
4470 port.
4471 If the port identified by Port is not open, undefined is re‐
4473 turned. If the port is closed and the calling process was previ‐
4474 ously linked to the port, the exit signal from the port is guar‐
4475 anteed to be delivered before port_info/2 returns undefined.
4476 Failure: badarg if Port is not a local port identifier, or an
4478 atom.
4479 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
4481 Types:
4483 Port = port() | atom()
4485 Index = integer() >= 0
4486 Index is the internal index of the port. This index can be used
4488 to separate ports.
4489 If the port identified by Port is not open, undefined is re‐
4491 turned. If the port is closed and the calling process was previ‐
4492 ously linked to the port, the exit signal from the port is guar‐
4493 anteed to be delivered before port_info/2 returns undefined.
4494 Failure: badarg if Port is not a local port identifier, or an
4496 atom.
4497 erlang:port_info(Port, Item :: input) ->
4499 {input, Bytes} | undefined
4500 Types:
4502 Port = port() | atom()
4504 Bytes = integer() >= 0
4505 Bytes is the total number of bytes read from the port.
4507 If the port identified by Port is not open, undefined is re‐
4509 turned. If the port is closed and the calling process was previ‐
4510 ously linked to the port, the exit signal from the port is guar‐
4511 anteed to be delivered before port_info/2 returns undefined.
4512 Failure: badarg if Port is not a local port identifier, or an
4514 atom.
4515 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4517 Types:
4519 Port = port() | atom()
4521 Pids = [pid()]
4522 Pids is a list of the process identifiers of the processes that
4524 the port is linked to.
4525 If the port identified by Port is not open, undefined is re‐
4527 turned. If the port is closed and the calling process was previ‐
4528 ously linked to the port, the exit signal from the port is guar‐
4529 anteed to be delivered before port_info/2 returns undefined.
4530 Failure: badarg if Port is not a local port identifier, or an
4532 atom.
4533 erlang:port_info(Port, Item :: locking) ->
4535 {locking, Locking} | undefined
4536 Types:
4538 Port = port() | atom()
4540 Locking = false | port_level | driver_level
4541 Locking is one of the following:
4543 * port_level (port-specific locking)
4545 * driver_level (driver-specific locking)
4547 Notice that these results are highly implementation-specific and
4549 can change in a future release.
4550 If the port identified by Port is not open, undefined is re‐
4552 turned. If the port is closed and the calling process was previ‐
4553 ously linked to the port, the exit signal from the port is guar‐
4554 anteed to be delivered before port_info/2 returns undefined.
4555 Failure: badarg if Port is not a local port identifier, or an
4557 atom.
4558 erlang:port_info(Port, Item :: memory) ->
4560 {memory, Bytes} | undefined
4561 Types:
4563 Port = port() | atom()
4565 Bytes = integer() >= 0
4566 Bytes is the total number of bytes allocated for this port by
4568 the runtime system. The port itself can have allocated memory
4569 that is not included in Bytes.
4570 If the port identified by Port is not open, undefined is re‐
4572 turned. If the port is closed and the calling process was previ‐
4573 ously linked to the port, the exit signal from the port is guar‐
4574 anteed to be delivered before port_info/2 returns undefined.
4575 Failure: badarg if Port is not a local port identifier, or an
4577 atom.
4578 erlang:port_info(Port, Item :: monitors) ->
4580 {monitors, Monitors} | undefined
4581 Types:
4583 Port = port() | atom()
4585 Monitors = [{process, pid()}]
4586 Monitors represent processes monitored by this port.
4588 If the port identified by Port is not open, undefined is re‐
4590 turned. If the port is closed and the calling process was previ‐
4591 ously linked to the port, the exit signal from the port is guar‐
4592 anteed to be delivered before port_info/2 returns undefined.
4593 Failure: badarg if Port is not a local port identifier, or an
4595 atom.
4596 erlang:port_info(Port, Item :: monitored_by) ->
4598 {monitored_by, MonitoredBy} | undefined
4599 Types:
4601 Port = port() | atom()
4603 MonitoredBy = [pid()]
4604 Returns list of pids that are monitoring given port at the mo‐
4606 ment.
4607 If the port identified by Port is not open, undefined is re‐
4609 turned. If the port is closed and the calling process was previ‐
4610 ously linked to the port, the exit signal from the port is guar‐
4611 anteed to be delivered before port_info/2 returns undefined.
4612 Failure: badarg if Port is not a local port identifier, or an
4614 atom.
4615 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
4617 Types:
4619 Port = port() | atom()
4621 Name = string()
4622 Name is the command name set by open_port/2.
4624 If the port identified by Port is not open, undefined is re‐
4626 turned. If the port is closed and the calling process was previ‐
4627 ously linked to the port, the exit signal from the port is guar‐
4628 anteed to be delivered before port_info/2 returns undefined.
4629 Failure: badarg if Port is not a local port identifier, or an
4631 atom.
4632 erlang:port_info(Port, Item :: os_pid) ->
4634 {os_pid, OsPid} | undefined
4635 Types:
4637 Port = port() | atom()
4639 OsPid = integer() >= 0 | undefined
4640 OsPid is the process identifier (or equivalent) of an OS process
4642 created with open_port({spawn | spawn_executable, Command}, Op‐
4643 tions). If the port is not the result of spawning an OS process,
4644 the value is undefined.
4645 If the port identified by Port is not open, undefined is re‐
4647 turned. If the port is closed and the calling process was previ‐
4648 ously linked to the port, the exit signal from the port is guar‐
4649 anteed to be delivered before port_info/2 returns undefined.
4650 Failure: badarg if Port is not a local port identifier, or an
4652 atom.
4653 erlang:port_info(Port, Item :: output) ->
4655 {output, Bytes} | undefined
4656 Types:
4658 Port = port() | atom()
4660 Bytes = integer() >= 0
4661 Bytes is the total number of bytes written to the port from Er‐
4663 lang processes using port_command/2, port_command/3, or Port !
4664 {Owner, {command, Data}.
4665 If the port identified by Port is not open, undefined is re‐
4667 turned. If the port is closed and the calling process was previ‐
4668 ously linked to the port, the exit signal from the port is guar‐
4669 anteed to be delivered before port_info/2 returns undefined.
4670 Failure: badarg if Port is not a local port identifier, or an
4672 atom.
4673 erlang:port_info(Port, Item :: parallelism) ->
4675 {parallelism, Boolean} | undefined
4676 Types:
4678 Port = port() | atom()
4680 Boolean = boolean()
4681 Boolean corresponds to the port parallelism hint used by this
4683 port. For more information, see option parallelism of
4684 open_port/2.
4685 erlang:port_info(Port, Item :: queue_size) ->
4687 {queue_size, Bytes} | undefined
4688 Types:
4690 Port = port() | atom()
4692 Bytes = integer() >= 0
4693 Bytes is the total number of bytes queued by the port using the
4695 ERTS driver queue implementation.
4696 If the port identified by Port is not open, undefined is re‐
4698 turned. If the port is closed and the calling process was previ‐
4699 ously linked to the port, the exit signal from the port is guar‐
4700 anteed to be delivered before port_info/2 returns undefined.
4701 Failure: badarg if Port is not a local port identifier, or an
4703 atom.
4704 erlang:port_info(Port, Item :: registered_name) ->
4706 {registered_name, RegisteredName} |
4707 [] | undefined
4708 Types:
4710 Port = port() | atom()
4712 RegisteredName = atom()
4713 RegisteredName is the registered name of the port. If the port
4715 has no registered name, [] is returned.
4716 If the port identified by Port is not open, undefined is re‐
4718 turned. If the port is closed and the calling process was previ‐
4719 ously linked to the port, the exit signal from the port is guar‐
4720 anteed to be delivered before port_info/2 returns undefined.
4721 Failure: badarg if Port is not a local port identifier, or an
4723 atom.
4724 port_to_list(Port) -> string()
4726 Types:
4728 Port = port()
4730 Returns a string corresponding to the text representation of the
4732 port identifier Port.
4733 erlang:ports() -> [port()]
4735 Returns a list of port identifiers corresponding to all the
4737 ports existing on the local node.
4738 Notice that an exiting port exists, but is not open.
4740 pre_loaded() -> [module()]
4742 Returns a list of Erlang modules that are preloaded in the sys‐
4744 tem. As all loading of code is done through the file system, the
4745 file system must have been loaded previously. Hence, at least
4746 the module init must be preloaded.
4747 erlang:process_display(Pid, Type) -> true
4749 Types:
4751 Pid = pid()
4753 Type = backtrace
4754 Writes information about the local process Pid on standard er‐
4756 ror. The only allowed value for the atom Type is backtrace,
4757 which shows the contents of the call stack, including informa‐
4758 tion about the call chain, with the current function printed
4759 first. The format of the output is not further defined.
4760 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4762 Types:
4764 Boolean = OldBoolean = boolean()
4766 When trap_exit is set to true, exit signals arriving to a
4768 process are converted to {'EXIT', From, Reason} messages, which
4769 can be received as ordinary messages. If trap_exit is set to
4770 false, the process exits if it receives an exit signal other
4771 than normal and the exit signal is propagated to its linked pro‐
4772 cesses. Application processes are normally not to trap exits.
4773 Returns the old value of the flag.
4775 See also exit/2.
4777 process_flag(Flag :: error_handler, Module) -> OldModule
4779 Types:
4781 Module = OldModule = atom()
4783 Used by a process to redefine the error handler for undefined
4785 function calls and undefined registered processes. Inexperienced
4786 users are not to use this flag, as code auto-loading depends on
4787 the correct operation of the error handling module.
4788 Returns the old value of the flag.
4790 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4792 Types:
4794 MinHeapSize = OldMinHeapSize = integer() >= 0
4796 Changes the minimum heap size for the calling process.
4798 Returns the old value of the flag.
4800 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4802 OldMinBinVHeapSize
4803 Types:
4805 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4807 Changes the minimum binary virtual heap size for the calling
4809 process.
4810 Returns the old value of the flag.
4812 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4814 Types:
4816 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4818 max_heap_size() =
4819 integer() >= 0 |
4820 #{size => integer() >= 0,
4821 kill => boolean(),
4822 error_logger => boolean()}
4823 This flag sets the maximum heap size for the calling process. If
4825 MaxHeapSize is an integer, the system default values for kill
4826 and error_logger are used.
4827 size:
4829 The maximum size in words of the process. If set to zero,
4830 the heap size limit is disabled. badarg is be thrown if the
4831 value is smaller than min_heap_size. The size check is only
4832 done when a garbage collection is triggered.
4833 size is the entire heap of the process when garbage collec‐
4835 tion is triggered. This includes all generational heaps, the
4836 process stack, any messages that are considered to be part
4837 of the heap, and any extra memory that the garbage collector
4838 needs during collection.
4839 size is the same as can be retrieved using er‐
4841 lang:process_info(Pid, total_heap_size), or by adding
4842 heap_block_size, old_heap_block_size and mbuf_size from er‐
4843 lang:process_info(Pid, garbage_collection_info).
4844 kill:
4846 When set to true, the runtime system sends an untrappable
4847 exit signal with reason kill to the process if the maximum
4848 heap size is reached. The garbage collection that triggered
4849 the kill is not completed, instead the process exits as soon
4850 as possible. When set to false, no exit signal is sent to
4851 the process, instead it continues executing.
4852 If kill is not defined in the map, the system default will
4854 be used. The default system default is true. It can be
4855 changed by either option +hmaxk in erl(1), or erlang:sys‐
4856 tem_flag(max_heap_size, MaxHeapSize).
4857 error_logger:
4859 When set to true, the runtime system logs an error event via
4860 logger, containing details about the process when the maxi‐
4861 mum heap size is reached. One log event is sent each time
4862 the limit is reached.
4863 If error_logger is not defined in the map, the system de‐
4865 fault is used. The default system default is true. It can be
4866 changed by either the option +hmaxel int erl(1), or er‐
4867 lang:system_flag(max_heap_size, MaxHeapSize).
4868 The heap size of a process is quite hard to predict, especially
4870 the amount of memory that is used during the garbage collection.
4871 When contemplating using this option, it is recommended to first
4872 run it in production with kill set to false and inspect the log
4873 events to see what the normal peak sizes of the processes in the
4874 system is and then tune the value accordingly.
4875 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4877 Types:
4879 MQD = OldMQD = message_queue_data()
4881 message_queue_data() = off_heap | on_heap
4882 Determines how messages in the message queue are stored, as fol‐
4884 lows:
4885 off_heap:
4887 All messages in the message queue will be stored outside the
4888 process heap. This implies that no messages in the message
4889 queue will be part of a garbage collection of the process.
4890 on_heap:
4892 All messages in the message queue will eventually be placed
4893 on the process heap. They can, however, be temporarily
4894 stored off the heap. This is how messages have always been
4895 stored up until ERTS 8.0.
4896 The default value of the message_queue_data process flag is de‐
4898 termined by the command-line argument +hmqd in erl(1).
4899 If the process may potentially accumulate a large number of mes‐
4901 sages in its queue it is recommended to set the flag value to
4902 off_heap. This is due to the fact that the garbage collection of
4903 a process that has a large number of messages stored on the heap
4904 can become extremely expensive and the process can consume large
4905 amounts of memory. The performance of the actual message passing
4906 is, however, generally better when the flag value is on_heap.
4907 Changing the flag value causes any existing messages to be
4909 moved. The move operation is initiated, but not necessarily com‐
4910 pleted, by the time the function returns.
4911 Returns the old value of the flag.
4913 process_flag(Flag :: priority, Level) -> OldLevel
4915 Types:
4917 Level = OldLevel = priority_level()
4919 priority_level() = low | normal | high | max
4920 Sets the process priority. Level is an atom. Four priority lev‐
4922 els exist: low, normal, high, and max. Default is normal.
4923 Note:
4925 Priority level max is reserved for internal use in the Erlang
4926 runtime system, and is not to be used by others.
4927 Internally in each priority level, processes are scheduled in a
4930 round robin fashion.
4931 Execution of processes on priority normal and low are inter‐
4933 leaved. Processes on priority low are selected for execution
4934 less frequently than processes on priority normal.
4935 When runnable processes on priority high exist, no processes on
4937 priority low or normal are selected for execution. Notice how‐
4938 ever that this does not mean that no processes on priority low
4939 or normal can run when processes are running on priority high.
4940 When using multiple schedulers, more processes can be running in
4941 parallel than processes on priority high. That is, a low and a
4942 high priority process can execute at the same time.
4943 When runnable processes on priority max exist, no processes on
4945 priority low, normal, or high are selected for execution. As
4946 with priority high, processes on lower priorities can execute in
4947 parallel with processes on priority max.
4948 Scheduling is pre-emptive. Regardless of priority, a process is
4950 pre-empted when it has consumed more than a certain number of
4951 reductions since the last time it was selected for execution.
4952 Note:
4954 Do not depend on the scheduling to remain exactly as it is to‐
4955 day. Scheduling is likely to be changed in a future release to
4956 use available processor cores better.
4957 There is no automatic mechanism for avoiding priority inversion,
4960 such as priority inheritance or priority ceilings. When using
4961 priorities, take this into account and handle such scenarios by
4962 yourself.
4963 Making calls from a high priority process into code that you has
4965 no control over can cause the high priority process to wait for
4966 a process with lower priority. That is, effectively decreasing
4967 the priority of the high priority process during the call. Even
4968 if this is not the case with one version of the code that you
4969 have no control over, it can be the case in a future version of
4970 it. This can, for example, occur if a high priority process
4971 triggers code loading, as the code server runs on priority nor‐
4972 mal.
4973 Other priorities than normal are normally not needed. When other
4975 priorities are used, use them with care, especially priority
4976 high. A process on priority high is only to perform work for
4977 short periods. Busy looping for long periods in a high priority
4978 process causes most likely problems, as important OTP servers
4979 run on priority normal.
4980 Returns the old value of the flag.
4982 process_flag(Flag :: save_calls, N) -> OldN
4984 Types:
4986 N = OldN = 0..10000
4988 N must be an integer in the interval 0..10000. If N > 0, call
4990 saving is made active for the process. This means that informa‐
4991 tion about the N most recent global function calls, BIF calls,
4992 sends, and receives made by the process are saved in a list,
4993 which can be retrieved with process_info(Pid, last_calls). A
4994 global function call is one in which the module of the function
4995 is explicitly mentioned. Only a fixed amount of information is
4996 saved, as follows:
4997 * A tuple {Module, Function, Arity} for function calls
4999 * The atoms send, 'receive', and timeout for sends and re‐
5001 ceives ('receive' when a message is received and timeout
5002 when a receive times out)
5003 If N = 0, call saving is disabled for the process, which is the
5005 default. Whenever the size of the call saving list is set, its
5006 contents are reset.
5007 Returns the old value of the flag.
5009 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
5011 Types:
5013 Boolean = OldBoolean = boolean()
5015 Sets or clears flag sensitive for the current process. When a
5017 process has been marked as sensitive by calling
5018 process_flag(sensitive, true), features in the runtime system
5019 that can be used for examining the data or inner working of the
5020 process are silently disabled.
5021 Features that are disabled include (but are not limited to) the
5023 following:
5024 * Tracing. Trace flags can still be set for the process, but
5026 no trace messages of any kind are generated. (If flag sensi‐
5027 tive is turned off, trace messages are again generated if
5028 any trace flags are set.)
5029 * Sequential tracing. The sequential trace token is propagated
5031 as usual, but no sequential trace messages are generated.
5032 process_info/1,2 cannot be used to read out the message queue or
5034 the process dictionary (both are returned as empty lists).
5035 Stack back-traces cannot be displayed for the process.
5037 In crash dumps, the stack, messages, and the process dictionary
5039 are omitted.
5040 If {save_calls,N} has been set for the process, no function
5042 calls are saved to the call saving list. (The call saving list
5043 is not cleared. Also, send, receive, and time-out events are
5044 still added to the list.)
5045 Returns the old value of the flag.
5047 process_flag(Pid, Flag, Value) -> OldValue
5049 Types:
5051 Pid = pid()
5053 Flag = save_calls
5054 Value = OldValue = integer() >= 0
5055 Sets certain flags for the process Pid, in the same manner as
5057 process_flag/2. Returns the old value of the flag. The valid
5058 values for Flag are only a subset of those allowed in
5059 process_flag/2, namely save_calls.
5060 Failure: badarg if Pid is not a local process.
5062 process_info(Pid) -> Info
5064 Types:
5066 Pid = pid()
5068 Info = [InfoTuple] | undefined
5069 InfoTuple = process_info_result_item()
5070 process_info_result_item() =
5071 {backtrace, Bin :: binary()} |
5072 {binary,
5073 BinInfo ::
5074 [{integer() >= 0,
5075 integer() >= 0,
5076 integer() >= 0}]} |
5077 {catchlevel, CatchLevel :: integer() >= 0} |
5078 {current_function,
5079 {Module :: module(), Function :: atom(), Arity :: arity()} |
5080 undefined} |
5081 {current_location,
5082 {Module :: module(),
5083 Function :: atom(),
5084 Arity :: arity(),
5085 Location ::
5086 [{file, Filename :: string()} |
5087 {line, Line :: integer() >= 1}]}} |
5088 {current_stacktrace, Stack :: [stack_item()]} |
5089 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5090 {error_handler, Module :: module()} |
5091 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5092 {garbage_collection_info,
5093 GCInfo :: [{atom(), integer() >= 0}]} |
5094 {group_leader, GroupLeader :: pid()} |
5095 {heap_size, Size :: integer() >= 0} |
5096 {initial_call, mfa()} |
5097 {links, PidsAndPorts :: [pid() | port()]} |
5098 {last_calls, false | (Calls :: [mfa()])} |
5099 {memory, Size :: integer() >= 0} |
5100 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5101 {messages, MessageQueue :: [term()]} |
5102 {min_heap_size, MinHeapSize :: integer() >= 0} |
5103 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5104 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5105 {monitored_by,
5106 MonitoredBy :: [pid() | port() | nif_resource()]} |
5107 {monitors,
5108 Monitors ::
5109 [{process | port,
5110 Pid ::
5111 pid() |
5112 port() |
5113 {RegName :: atom(), Node :: node()}}]} |
5114 {message_queue_data, MQD :: message_queue_data()} |
5115 {priority, Level :: priority_level()} |
5116 {reductions, Number :: integer() >= 0} |
5117 {registered_name, [] | (Atom :: atom())} |
5118 {sequential_trace_token,
5119 [] | (SequentialTraceToken :: term())} |
5120 {stack_size, Size :: integer() >= 0} |
5121 {status,
5122 Status ::
5123 exiting | garbage_collecting | waiting | running |
5124 runnable | suspended} |
5125 {suspending,
5126 SuspendeeList ::
5127 [{Suspendee :: pid(),
5128 ActiveSuspendCount :: integer() >= 0,
5129 OutstandingSuspendCount :: integer() >= 0}]} |
5130 {total_heap_size, Size :: integer() >= 0} |
5131 {trace, InternalTraceFlags :: integer() >= 0} |
5132 {trap_exit, Boolean :: boolean()}
5133 priority_level() = low | normal | high | max
5134 stack_item() =
5135 {Module :: module(),
5136 Function :: atom(),
5137 Arity :: arity() | (Args :: [term()]),
5138 Location ::
5139 [{file, Filename :: string()} |
5140 {line, Line :: integer() >= 1}]}
5141 max_heap_size() =
5142 integer() >= 0 |
5143 #{size => integer() >= 0,
5144 kill => boolean(),
5145 error_logger => boolean()}
5146 message_queue_data() = off_heap | on_heap
5147 Returns a list containing InfoTuples with miscellaneous informa‐
5149 tion about the process identified by Pid, or undefined if the
5150 process is not alive.
5151 The order of the InfoTuples is undefined and all InfoTuples are
5153 not mandatory. The InfoTuples part of the result can be changed
5154 without prior notice.
5155 The InfoTuples with the following items are part of the result:
5157 * current_function
5159 * initial_call
5161 * status
5163 * message_queue_len
5165 * links
5167 * dictionary
5169 * trap_exit
5171 * error_handler
5173 * priority
5175 * group_leader
5177 * total_heap_size
5179 * heap_size
5181 * stack_size
5183 * reductions
5185 * garbage_collection
5187 If the process identified by Pid has a registered name, also an
5189 InfoTuple with item registered_name is included.
5190 For information about specific InfoTuples, see process_info/2.
5192 Warning:
5194 This BIF is intended for debugging only. For all other purposes,
5195 use process_info/2.
5196 Failure: badarg if Pid is not a local process.
5199 process_info(Pid, Item) -> InfoTuple | [] | undefined
5201 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5203 Types:
5205 Pid = pid()
5207 ItemList = [Item]
5208 Item = process_info_item()
5209 InfoTupleList = [InfoTuple]
5210 InfoTuple = process_info_result_item()
5211 process_info_item() =
5212 backtrace | binary | catchlevel | current_function |
5213 current_location | current_stacktrace | dictionary |
5214 error_handler | garbage_collection | garbage_collection_info |
5215 group_leader | heap_size | initial_call | links | last_calls |
5216 memory | message_queue_len | messages | min_heap_size |
5217 min_bin_vheap_size | monitored_by | monitors |
5218 message_queue_data | priority | reductions | registered_name |
5219 sequential_trace_token | stack_size | status | suspending |
5220 total_heap_size | trace | trap_exit
5221 process_info_result_item() =
5222 {backtrace, Bin :: binary()} |
5223 {binary,
5224 BinInfo ::
5225 [{integer() >= 0,
5226 integer() >= 0,
5227 integer() >= 0}]} |
5228 {catchlevel, CatchLevel :: integer() >= 0} |
5229 {current_function,
5230 {Module :: module(), Function :: atom(), Arity :: arity()} |
5231 undefined} |
5232 {current_location,
5233 {Module :: module(),
5234 Function :: atom(),
5235 Arity :: arity(),
5236 Location ::
5237 [{file, Filename :: string()} |
5238 {line, Line :: integer() >= 1}]}} |
5239 {current_stacktrace, Stack :: [stack_item()]} |
5240 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5241 {error_handler, Module :: module()} |
5242 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5243 {garbage_collection_info,
5244 GCInfo :: [{atom(), integer() >= 0}]} |
5245 {group_leader, GroupLeader :: pid()} |
5246 {heap_size, Size :: integer() >= 0} |
5247 {initial_call, mfa()} |
5248 {links, PidsAndPorts :: [pid() | port()]} |
5249 {last_calls, false | (Calls :: [mfa()])} |
5250 {memory, Size :: integer() >= 0} |
5251 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5252 {messages, MessageQueue :: [term()]} |
5253 {min_heap_size, MinHeapSize :: integer() >= 0} |
5254 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5255 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5256 {monitored_by,
5257 MonitoredBy :: [pid() | port() | nif_resource()]} |
5258 {monitors,
5259 Monitors ::
5260 [{process | port,
5261 Pid ::
5262 pid() |
5263 port() |
5264 {RegName :: atom(), Node :: node()}}]} |
5265 {message_queue_data, MQD :: message_queue_data()} |
5266 {priority, Level :: priority_level()} |
5267 {reductions, Number :: integer() >= 0} |
5268 {registered_name, [] | (Atom :: atom())} |
5269 {sequential_trace_token,
5270 [] | (SequentialTraceToken :: term())} |
5271 {stack_size, Size :: integer() >= 0} |
5272 {status,
5273 Status ::
5274 exiting | garbage_collecting | waiting | running |
5275 runnable | suspended} |
5276 {suspending,
5277 SuspendeeList ::
5278 [{Suspendee :: pid(),
5279 ActiveSuspendCount :: integer() >= 0,
5280 OutstandingSuspendCount :: integer() >= 0}]} |
5281 {total_heap_size, Size :: integer() >= 0} |
5282 {trace, InternalTraceFlags :: integer() >= 0} |
5283 {trap_exit, Boolean :: boolean()}
5284 stack_item() =
5285 {Module :: module(),
5286 Function :: atom(),
5287 Arity :: arity() | (Args :: [term()]),
5288 Location ::
5289 [{file, Filename :: string()} |
5290 {line, Line :: integer() >= 1}]}
5291 priority_level() = low | normal | high | max
5292 max_heap_size() =
5293 integer() >= 0 |
5294 #{size => integer() >= 0,
5295 kill => boolean(),
5296 error_logger => boolean()}
5297 message_queue_data() = off_heap | on_heap
5298 Returns information about the process identified by Pid, as
5300 specified by Item or ItemList. Returns undefined if the process
5301 is not alive.
5302 If the process is alive and a single Item is specified, the re‐
5304 turned value is the corresponding InfoTuple, unless Item =:=
5305 registered_name and the process has no registered name. In this
5306 case, [] is returned. This strange behavior is because of his‐
5307 torical reasons, and is kept for backward compatibility.
5308 If ItemList is specified, the result is InfoTupleList. The Info‐
5310 Tuples in InfoTupleList are included with the corresponding
5311 Items in the same order as the Items were included in ItemList.
5312 Valid Items can be included multiple times in ItemList.
5313 Note:
5315 If registered_name is part of ItemList and the process has no
5316 name registered, a {registered_name, []}, InfoTuple will be in‐
5317 cluded in the resulting InfoTupleList. This behavior is differ‐
5318 ent when a single Item =:= registered_name is specified, and
5319 when process_info/1 is used.
5320 Valid InfoTuples with corresponding Items:
5323 {backtrace, Bin}:
5325 Binary Bin contains the same information as the output from
5326 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5327 to obtain the string of characters from the binary.
5328 {binary, BinInfo}:
5330 BinInfo is a list containing miscellaneous information about
5331 binaries on the heap of this process. This InfoTuple can be
5332 changed or removed without prior notice. In the current im‐
5333 plementation BinInfo is a list of tuples. The tuples con‐
5334 tain; BinaryId, BinarySize, BinaryRefcCount.
5335 Depending on the value of the message_queue_data process
5337 flag the message queue may be stored on the heap.
5338 {catchlevel, CatchLevel}:
5340 CatchLevel is the number of currently active catches in this
5341 process. This InfoTuple can be changed or removed without
5342 prior notice.
5343 {current_function, {Module, Function, Arity} | undefined}:
5345 Module, Function, Arity is the current function call of the
5346 process. The value undefined can be returned if the process
5347 is currently executing native compiled code.
5348 {current_location, {Module, Function, Arity, Location}}:
5350 Module, Function, Arity is the current function call of the
5351 process. Location is a list of two-tuples describing the lo‐
5352 cation in the source code.
5353 {current_stacktrace, Stack}:
5355 Returns the current call stack back-trace (stacktrace) of
5356 the process. The stack has the same format as in the catch
5357 part of a try. See The call-stack back trace (stacktrace).
5358 The depth of the stacktrace is truncated according to the
5359 backtrace_depth system flag setting.
5360 {dictionary, Dictionary}:
5362 Dictionary is the process dictionary.
5363 {error_handler, Module}:
5365 Module is the error handler module used by the process (for
5366 undefined function calls, for example).
5367 {garbage_collection, GCInfo}:
5369 GCInfo is a list containing miscellaneous information about
5370 garbage collection for this process. The content of GCInfo
5371 can be changed without prior notice.
5372 {garbage_collection_info, GCInfo}:
5374 GCInfo is a list containing miscellaneous detailed informa‐
5375 tion about garbage collection for this process. The content
5376 of GCInfo can be changed without prior notice. For details
5377 about the meaning of each item, see gc_minor_start in er‐
5378 lang:trace/3.
5379 {group_leader, GroupLeader}:
5381 GroupLeader is the group leader for the I/O of the process.
5382 {heap_size, Size}:
5384 Size is the size in words of the youngest heap generation of
5385 the process. This generation includes the process stack.
5386 This information is highly implementation-dependent, and can
5387 change if the implementation changes.
5388 {initial_call, {Module, Function, Arity}}:
5390 Module, Function, Arity is the initial function call with
5391 which the process was spawned.
5392 {links, PidsAndPorts}:
5394 PidsAndPorts is a list of process identifiers and port iden‐
5395 tifiers, with processes or ports to which the process has a
5396 link.
5397 {last_calls, false|Calls}:
5399 The value is false if call saving is not active for the
5400 process (see process_flag/3). If call saving is active, a
5401 list is returned, in which the last element is the most re‐
5402 cent called.
5403 {memory, Size}:
5405 Size is the size in bytes of the process. This includes call
5408 stack, heap, and internal structures.
5409 {message_queue_len, MessageQueueLen}:
5411 MessageQueueLen is the number of messages currently in the
5412 message queue of the process. This is the length of the list
5413 MessageQueue returned as the information item messages (see
5414 below).
5415 {messages, MessageQueue}:
5417 MessageQueue is a list of the messages to the process, which
5418 have not yet been processed.
5419 {min_heap_size, MinHeapSize}:
5421 MinHeapSize is the minimum heap size for the process.
5422 {min_bin_vheap_size, MinBinVHeapSize}:
5424 MinBinVHeapSize is the minimum binary virtual heap size for
5425 the process.
5426 {monitored_by, MonitoredBy}:
5428 A list of identifiers for all the processes, ports and NIF
5429 resources, that are monitoring the process.
5430 {monitors, Monitors}:
5432 A list of monitors (started by monitor/2) that are active
5433 for the process. For a local process monitor or a remote
5434 process monitor by a process identifier, the list consists
5435 of:
5436 {process, Pid}:
5438 Process is monitored by pid.
5439 {process, {RegName, Node}}:
5441 Local or remote process is monitored by name.
5442 {port, PortId}:
5444 Local port is monitored by port id.
5445 {port, {RegName, Node}}:
5447 Local port is monitored by name. Please note, that remote
5448 port monitors are not supported, so Node will always be
5449 the local node name.
5450 {message_queue_data, MQD}:
5452 MQD is the current value of the message_queue_data process
5453 flag, which can be either off_heap or on_heap. For more in‐
5454 formation, see the documentation of process_flag(mes‐
5455 sage_queue_data, MQD).
5456 {priority, Level}:
5458 Level is the current priority level for the process. For
5459 more information on priorities, see process_flag(priority,
5460 Level).
5461 {reductions, Number}:
5463 Number is the number of reductions executed by the process.
5464 {registered_name, Atom}:
5466 Atom is the registered process name. If the process has no
5467 registered name, this tuple is not present in the list.
5468 {sequential_trace_token, [] | SequentialTraceToken}:
5470 SequentialTraceToken is the sequential trace token for the
5471 process. This InfoTuple can be changed or removed without
5472 prior notice.
5473 {stack_size, Size}:
5475 Size is the stack size, in words, of the process.
5476 {status, Status}:
5478 Status is the status of the process and is one of the fol‐
5479 lowing:
5480 * exiting
5482 * garbage_collecting
5484 * waiting (for a message)
5486 * running
5488 * runnable (ready to run, but another process is running)
5490 * suspended (suspended on a "busy" port or by the BIF er‐
5492 lang:suspend_process/1,2)
5493 {suspending, SuspendeeList}:
5495 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5496 OutstandingSuspendCount} tuples. Suspendee is the process
5497 identifier of a process that has been, or is to be, sus‐
5498 pended by the process identified by Pid through the BIF er‐
5499 lang:suspend_process/2 or erlang:suspend_process/1.
5500 ActiveSuspendCount is the number of times Suspendee has been
5502 suspended by Pid. OutstandingSuspendCount is the number of
5503 not yet completed suspend requests sent by Pid, that is:
5504 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5506 suspended state.
5507 * If OutstandingSuspendCount =/= 0, option asynchronous of
5509 erlang:suspend_process/2 has been used and the suspendee
5510 has not yet been suspended by Pid.
5511 Notice that ActiveSuspendCount and OutstandingSuspendCount
5513 are not the total suspend count on Suspendee, only the parts
5514 contributed by Pid.
5515 {total_heap_size, Size}:
5517 Size is the total size, in words, of all heap fragments of
5518 the process. This includes the process stack and any unre‐
5519 ceived messages that are considered to be part of the heap.
5520 {trace, InternalTraceFlags}:
5522 InternalTraceFlags is an integer representing the internal
5523 trace flag for this process. This InfoTuple can be changed
5524 or removed without prior notice.
5525 {trap_exit, Boolean}:
5527 Boolean is true if the process is trapping exits, otherwise
5528 false.
5529 Notice that not all implementations support all these Items.
5531 Failures:
5533 badarg:
5535 If Pid is not a local process.
5536 badarg:
5538 If Item is an invalid item.
5539 processes() -> [pid()]
5541 Returns a list of process identifiers corresponding to all the
5543 processes currently existing on the local node.
5544 Notice that an exiting process exists, but is not alive. That
5546 is, is_process_alive/1 returns false for an exiting process, but
5547 its process identifier is part of the result returned from pro‐
5548 cesses/0.
5549 Example:
5551 > processes().
5553 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5554 purge_module(Module) -> true
5556 Types:
5558 Module = atom()
5560 Removes old code for Module. Before this BIF is used,
5562 check_process_code/2 is to be called to check that no processes
5563 execute old code in the module.
5564 Warning:
5566 This BIF is intended for the code server (see code(3)) and is
5567 not to be used elsewhere.
5568 Note:
5571 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5572 still execute the old code is killed by this function. In ear‐
5573 lier versions, such incorrect use could cause much more fatal
5574 failures, like emulator crash.
5575 Failure: badarg if there is no old code for Module.
5578 put(Key, Val) -> term()
5580 Types:
5582 Key = Val = term()
5584 Adds a new Key to the process dictionary, associated with the
5586 value Val, and returns undefined. If Key exists, the old value
5587 is deleted and replaced by Val, and the function returns the old
5588 value. Example:
5589 > X = put(name, walrus), Y = put(name, carpenter),
5591 Z = get(name),
5592 {X, Y, Z}.
5593 {undefined,walrus,carpenter}
5594 Note:
5596 The values stored when put is evaluated within the scope of a
5597 catch are not retracted if a throw is evaluated, or if an error
5598 occurs.
5599 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5602 Types:
5604 Class = error | exit | throw
5606 Reason = term()
5607 Stacktrace = raise_stacktrace()
5608 raise_stacktrace() =
5609 [{module(), atom(), arity() | [term()]} |
5610 {function(), [term()]}] |
5611 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5612 {function(), [term()], [{atom(), term()}]}]
5613 Stops the execution of the calling process with an exception of
5615 the specified class, reason, and call stack backtrace (stack‐
5616 trace).
5617 Class is error, exit, or throw. So, if it were not for the
5619 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5620 lent to erlang:Class(Reason).
5621 Reason can be any term.
5623 Stacktrace is a list as provided in a try-catch clause.
5625 try
5627 ...
5628 catch Class:Reason:Stacktrace ->
5629 ...
5630 end
5631 That is, a list of four-tuples {Module, Function, Arity | Args,
5633 Location}, where Module and Function are atoms, and the third
5634 element is an integer arity or an argument list. The stacktrace
5635 can also contain {Fun, Args, Location} tuples, where Fun is a
5636 local fun and Args is an argument list.
5637 Element Location at the end is optional. Omitting it is equiva‐
5639 lent to specifying an empty list.
5640 The stacktrace is used as the exception stacktrace for the call‐
5642 ing process; it is truncated to the current maximum stacktrace
5643 depth.
5644 As evaluating this function causes the process to terminate, it
5646 has no return value unless the arguments are invalid, in which
5647 case the function returns the error reason badarg. If you want
5648 to be sure not to return, you can call error(erlang:raise(Class,
5649 Reason, Stacktrace)) and hope to distinguish exceptions later.
5650 erlang:read_timer(TimerRef) -> Result
5652 Types:
5654 TimerRef = reference()
5656 Time = integer() >= 0
5657 Result = Time | false
5658 Reads the state of a timer. The same as calling er‐
5660 lang:read_timer(TimerRef, []).
5661 erlang:read_timer(TimerRef, Options) -> Result | ok
5663 Types:
5665 TimerRef = reference()
5667 Async = boolean()
5668 Option = {async, Async}
5669 Options = [Option]
5670 Time = integer() >= 0
5671 Result = Time | false
5672 Reads the state of a timer that has been created by either er‐
5674 lang:start_timer or erlang:send_after. TimerRef identifies the
5675 timer, and was returned by the BIF that created the timer.
5676 Options:
5678 {async, Async}:
5680 Asynchronous request for state information. Async defaults
5681 to false, which causes the operation to be performed syn‐
5682 chronously. In this case, the Result is returned by er‐
5683 lang:read_timer. When Async is true, erlang:read_timer sends
5684 an asynchronous request for the state information to the
5685 timer service that manages the timer, and then returns ok. A
5686 message on the format {read_timer, TimerRef, Result} is sent
5687 to the caller of erlang:read_timer when the operation has
5688 been processed.
5689 More Options can be added in the future.
5691 If Result is an integer, it represents the time in milliseconds
5693 left until the timer expires.
5694 If Result is false, a timer corresponding to TimerRef could not
5696 be found. This because the timer had expired, or been canceled,
5697 or because TimerRef never has corresponded to a timer. Even if
5698 the timer has expired, it does not tell you whether or not the
5699 time-out message has arrived at its destination yet.
5700 Note:
5702 The timer service that manages the timer can be co-located with
5703 another scheduler than the scheduler that the calling process is
5704 executing on. If so, communication with the timer service takes
5705 much longer time than if it is located locally. If the calling
5706 process is in a critical path, and can do other things while
5707 waiting for the result of this operation, you want to use option
5708 {async, true}. If using option {async, false}, the calling
5709 process is blocked until the operation has been performed.
5710 See also erlang:send_after/4, erlang:start_timer/4, and er‐
5713 lang:cancel_timer/2.
5714 ref_to_list(Ref) -> string()
5716 Types:
5718 Ref = reference()
5720 Returns a string corresponding to the text representation of
5722 Ref.
5723 Warning:
5725 This BIF is intended for debugging and is not to be used in ap‐
5726 plication programs.
5727 register(RegName, PidOrPort) -> true
5730 Types:
5732 RegName = atom()
5734 PidOrPort = port() | pid()
5735 Associates the name RegName with a process identifier (pid) or a
5737 port identifier. RegName, which must be an atom, can be used in‐
5738 stead of the pid or port identifier in send operator (RegName !
5739 Message). Example:
5740 > register(db, Pid).
5742 true
5743 Failures:
5745 badarg:
5747 If PidOrPort is not an existing local process or port.
5748 badarg:
5750 If RegName is already in use.
5751 badarg:
5753 If the process or port is already registered (already has a
5754 name).
5755 badarg:
5757 If RegName is the atom undefined.
5758 registered() -> [RegName]
5760 Types:
5762 RegName = atom()
5764 Returns a list of names that have been registered using regis‐
5766 ter/2, for example:
5767 > registered().
5769 [code_server, file_server, init, user, my_db]
5770 erlang:resume_process(Suspendee) -> true
5772 Types:
5774 Suspendee = pid()
5776 Decreases the suspend count on the process identified by Sus‐
5778 pendee. Suspendee is previously to have been suspended through
5779 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5780 process calling erlang:resume_process(Suspendee). When the sus‐
5781 pend count on Suspendee reaches zero, Suspendee is resumed, that
5782 is, its state is changed from suspended into the state it had
5783 before it was suspended.
5784 Warning:
5786 This BIF is intended for debugging only.
5787 Failures:
5790 badarg:
5792 If Suspendee is not a process identifier.
5793 badarg:
5795 If the process calling erlang:resume_process/1 had not pre‐
5796 viously increased the suspend count on the process identi‐
5797 fied by Suspendee.
5798 badarg:
5800 If the process identified by Suspendee is not alive.
5801 round(Number) -> integer()
5803 Types:
5805 Number = number()
5807 Returns an integer by rounding Number, for example:
5809 round(5.5).
5811 6
5812 Allowed in guard tests.
5814 self() -> pid()
5816 Returns the process identifier of the calling process, for exam‐
5818 ple:
5819 > self().
5821 <0.26.0>
5822 Allowed in guard tests.
5824 erlang:send(Dest, Msg) -> Msg
5826 Types:
5828 Dest = dst()
5830 Msg = term()
5831 dst() =
5832 pid() |
5833 port() |
5834 (RegName :: atom()) |
5835 {RegName :: atom(), Node :: node()}
5836 Sends a message and returns Msg. This is the same as using the
5838 send operator: Dest ! Msg.
5839 Dest can be a remote or local process identifier, a (local)
5841 port, a locally registered name, or a tuple {RegName, Node} for
5842 a registered name at another node.
5843 The function fails with a badarg run-time error if Dest is an
5845 atom name, but this name is not registered. This is the only
5846 case when send fails for an unreachable destination Dest (of
5847 correct type).
5848 erlang:send(Dest, Msg, Options) -> Res
5850 Types:
5852 Dest = dst()
5854 Msg = term()
5855 Options = [nosuspend | noconnect]
5856 Res = ok | nosuspend | noconnect
5857 dst() =
5858 pid() |
5859 port() |
5860 (RegName :: atom()) |
5861 {RegName :: atom(), Node :: node()}
5862 Either sends a message and returns ok, or does not send the mes‐
5864 sage but returns something else (see below). Otherwise the same
5865 as erlang:send/2. For more detailed explanation and warnings,
5866 see erlang:send_nosuspend/2,3.
5867 Options:
5869 nosuspend:
5871 If the sender would have to be suspended to do the send, no‐
5872 suspend is returned instead.
5873 noconnect:
5875 If the destination node would have to be auto-connected to
5876 do the send, noconnect is returned instead.
5877 Warning:
5879 As with erlang:send_nosuspend/2,3: use with extreme care.
5880 erlang:send_after(Time, Dest, Msg) -> TimerRef
5883 Types:
5885 Time = integer() >= 0
5887 Dest = pid() | atom()
5888 Msg = term()
5889 TimerRef = reference()
5890 Starts a timer. The same as calling erlang:send_after(Time,
5892 Dest, Msg, []).
5893 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5895 Types:
5897 Time = integer()
5899 Dest = pid() | atom()
5900 Msg = term()
5901 Options = [Option]
5902 Abs = boolean()
5903 Option = {abs, Abs}
5904 TimerRef = reference()
5905 Starts a timer. When the timer expires, the message Msg is sent
5907 to the process identified by Dest. Apart from the format of the
5908 time-out message, this function works exactly as er‐
5909 lang:start_timer/4.
5910 erlang:send_nosuspend(Dest, Msg) -> boolean()
5912 Types:
5914 Dest = dst()
5916 Msg = term()
5917 dst() =
5918 pid() |
5919 port() |
5920 (RegName :: atom()) |
5921 {RegName :: atom(), Node :: node()}
5922 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5924 true if the message was sent and false if the message was not
5925 sent because the sender would have had to be suspended.
5926 This function is intended for send operations to an unreliable
5928 remote node without ever blocking the sending (Erlang) process.
5929 If the connection to the remote node (usually not a real Erlang
5930 node, but a node written in C or Java) is overloaded, this func‐
5931 tion does not send the message and returns false.
5932 The same occurs if Dest refers to a local port that is busy. For
5934 all other destinations (allowed for the ordinary send operator
5935 '!'), this function sends the message and returns true.
5936 This function is only to be used in rare circumstances where a
5938 process communicates with Erlang nodes that can disappear with‐
5939 out any trace, causing the TCP buffers and the drivers queue to
5940 be over-full before the node is shut down (because of tick time-
5941 outs) by net_kernel. The normal reaction to take when this oc‐
5942 curs is some kind of premature shutdown of the other node.
5943 Notice that ignoring the return value from this function would
5945 result in an unreliable message passing, which is contradictory
5946 to the Erlang programming model. The message is not sent if this
5947 function returns false.
5948 In many systems, transient states of overloaded queues are nor‐
5950 mal. Although this function returns false does not mean that the
5951 other node is guaranteed to be non-responsive, it could be a
5952 temporary overload. Also, a return value of true does only mean
5953 that the message can be sent on the (TCP) channel without block‐
5954 ing; the message is not guaranteed to arrive at the remote node.
5955 For a disconnected non-responsive node, the return value is true
5956 (mimics the behavior of operator !). The expected behavior and
5957 the actions to take when the function returns false are applica‐
5958 tion- and hardware-specific.
5959 Warning:
5961 Use with extreme care.
5962 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5965 Types:
5967 Dest = dst()
5969 Msg = term()
5970 Options = [noconnect]
5971 dst() =
5972 pid() |
5973 port() |
5974 (RegName :: atom()) |
5975 {RegName :: atom(), Node :: node()}
5976 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5978 with a Boolean return value.
5979 This function behaves like erlang:send_nosuspend/2, but takes a
5981 third parameter, a list of options. The only option is nocon‐
5982 nect, which makes the function return false if the remote node
5983 is not currently reachable by the local node. The normal behav‐
5984 ior is to try to connect to the node, which can stall the
5985 process during a short period. The use of option noconnect makes
5986 it possible to be sure not to get the slightest delay when send‐
5987 ing to a remote process. This is especially useful when communi‐
5988 cating with nodes that expect to always be the connecting part
5989 (that is, nodes written in C or Java).
5990 Whenever the function returns false (either when a suspend would
5992 occur or when noconnect was specified and the node was not al‐
5993 ready connected), the message is guaranteed not to have been
5994 sent.
5995 Warning:
5997 Use with extreme care.
5998 erlang:set_cookie(Node, Cookie) -> true
6001 Types:
6003 Node = node()
6005 Cookie = atom()
6006 Sets the magic cookie of Node to the atom Cookie. If Node is the
6008 local node, the function also sets the cookie of all other un‐
6009 known nodes to Cookie (see section Distributed Erlang in the
6010 Erlang Reference Manual in System Documentation).
6011 Failure: function_clause if the local node is not alive.
6013 setelement(Index, Tuple1, Value) -> Tuple2
6015 Types:
6017 Index = integer() >= 1
6019 1..tuple_size(Tuple1
6020 Tuple1 = Tuple2 = tuple()
6021 Value = term()
6022 Returns a tuple that is a copy of argument Tuple1 with the ele‐
6024 ment specified by integer argument Index (the first element is
6025 the element with index 1) replaced by argument Value, for exam‐
6026 ple:
6027 > setelement(2, {10, green, bottles}, red).
6029 {10,red,bottles}
6030 size(Item) -> integer() >= 0
6032 Types:
6034 Item = tuple() | binary()
6036 Returns the number of elements in a tuple or the number of bytes
6038 in a binary or bitstring, for example:
6039 > size({morni, mulle, bwange}).
6041 3
6042 > size(<<11, 22, 33>>).
6043 3
6044 For bitstrings, the number of whole bytes is returned. That is,
6046 if the number of bits in the bitstring is not divisible by 8,
6047 the resulting number of bytes is rounded down.
6048 Allowed in guard tests.
6050 See also tuple_size/1, byte_size/1, and bit_size/1.
6052 spawn(Fun) -> pid()
6054 Types:
6056 Fun = function()
6058 Returns the process identifier of a new process started by the
6060 application of Fun to the empty list []. Otherwise works like
6061 spawn/3.
6062 spawn(Node, Fun) -> pid()
6064 Types:
6066 Node = node()
6068 Fun = function()
6069 Returns the process identifier of a new process started by the
6071 application of Fun to the empty list [] on Node. If Node does
6072 not exist, a useless pid is returned. Otherwise works like
6073 spawn/3.
6074 spawn(Module, Function, Args) -> pid()
6076 Types:
6078 Module = module()
6080 Function = atom()
6081 Args = [term()]
6082 Returns the process identifier of a new process started by the
6084 application of Module:Function to Args.
6085 error_handler:undefined_function(Module, Function, Args) is
6087 evaluated by the new process if Module:Function/Arity does not
6088 exist (where Arity is the length of Args). The error handler can
6089 be redefined (see process_flag/2). If error_handler is unde‐
6090 fined, or the user has redefined the default error_handler and
6091 its replacement is undefined, a failure with reason undef oc‐
6092 curs.
6093 Example:
6095 > spawn(speed, regulator, [high_speed, thin_cut]).
6097 <0.13.1>
6098 spawn(Node, Module, Function, Args) -> pid()
6100 Types:
6102 Node = node()
6104 Module = module()
6105 Function = atom()
6106 Args = [term()]
6107 Returns the process identifier (pid) of a new process started by
6109 the application of Module:Function to Args on Node. If Node does
6110 not exist, a useless pid is returned. Otherwise works like
6111 spawn/3.
6112 spawn_link(Fun) -> pid()
6114 Types:
6116 Fun = function()
6118 Returns the process identifier of a new process started by the
6120 application of Fun to the empty list []. A link is created be‐
6121 tween the calling process and the new process, atomically. Oth‐
6122 erwise works like spawn/3.
6123 spawn_link(Node, Fun) -> pid()
6125 Types:
6127 Node = node()
6129 Fun = function()
6130 Returns the process identifier (pid) of a new process started by
6132 the application of Fun to the empty list [] on Node. A link is
6133 created between the calling process and the new process, atomi‐
6134 cally. If Node does not exist, a useless pid is returned and an
6135 exit signal with reason noconnection is sent to the calling
6136 process. Otherwise works like spawn/3.
6137 spawn_link(Module, Function, Args) -> pid()
6139 Types:
6141 Module = module()
6143 Function = atom()
6144 Args = [term()]
6145 Returns the process identifier of a new process started by the
6147 application of Module:Function to Args. A link is created be‐
6148 tween the calling process and the new process, atomically. Oth‐
6149 erwise works like spawn/3.
6150 spawn_link(Node, Module, Function, Args) -> pid()
6152 Types:
6154 Node = node()
6156 Module = module()
6157 Function = atom()
6158 Args = [term()]
6159 Returns the process identifier (pid) of a new process started by
6161 the application of Module:Function to Args on Node. A link is
6162 created between the calling process and the new process, atomi‐
6163 cally. If Node does not exist, a useless pid is returned and an
6164 exit signal with reason noconnection is sent to the calling
6165 process. Otherwise works like spawn/3.
6166 spawn_monitor(Fun) -> {pid(), reference()}
6168 Types:
6170 Fun = function()
6172 Returns the process identifier of a new process, started by the
6174 application of Fun to the empty list [], and a reference for a
6175 monitor created to the new process. Otherwise works like
6176 spawn/3.
6177 spawn_monitor(Node, Fun) -> {pid(), reference()}
6179 Types:
6181 Node = node()
6183 Fun = function()
6184 Returns the process identifier of a new process, started by the
6186 application of Fun to the empty list [] on the node Node, and a
6187 reference for a monitor created to the new process. Otherwise
6188 works like spawn/3.
6189 If the node identified by Node does not support distributed
6191 spawn_monitor(), the call will fail with a notsup exception.
6192 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6194 Types:
6196 Module = module()
6198 Function = atom()
6199 Args = [term()]
6200 A new process is started by the application of Module:Function
6202 to Args. The process is monitored at the same time. Returns the
6203 process identifier and a reference for the monitor. Otherwise
6204 works like spawn/3.
6205 spawn_monitor(Node, Module, Function, Args) ->
6207 {pid(), reference()}
6208 Types:
6210 Node = node()
6212 Module = module()
6213 Function = atom()
6214 Args = [term()]
6215 A new process is started by the application of Module:Function
6217 to Args on the node Node. The process is monitored at the same
6218 time. Returns the process identifier and a reference for the
6219 monitor. Otherwise works like spawn/3.
6220 If the node identified by Node does not support distributed
6222 spawn_monitor(), the call will fail with a notsup exception.
6223 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6225 Types:
6227 Fun = function()
6229 Options = [spawn_opt_option()]
6230 priority_level() = low | normal | high | max
6231 max_heap_size() =
6232 integer() >= 0 |
6233 #{size => integer() >= 0,
6234 kill => boolean(),
6235 error_logger => boolean()}
6236 message_queue_data() = off_heap | on_heap
6237 spawn_opt_option() =
6238 link | monitor |
6239 {priority, Level :: priority_level()} |
6240 {fullsweep_after, Number :: integer() >= 0} |
6241 {min_heap_size, Size :: integer() >= 0} |
6242 {min_bin_vheap_size, VSize :: integer() >= 0} |
6243 {max_heap_size, Size :: max_heap_size()} |
6244 {message_queue_data, MQD :: message_queue_data()}
6245 Returns the process identifier (pid) of a new process started by
6247 the application of Fun to the empty list []. Otherwise works
6248 like spawn_opt/4.
6249 If option monitor is specified, the newly created process is
6251 monitored, and both the pid and reference for the monitor are
6252 returned.
6253 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6255 Types:
6257 Node = node()
6259 Fun = function()
6260 Options = [monitor | link | OtherOption]
6261 OtherOption = term()
6262 Returns the process identifier (pid) of a new process started by
6264 the application of Fun to the empty list [] on Node. If Node
6265 does not exist, a useless pid is returned. Otherwise works like
6266 spawn_opt/4.
6267 Valid options depends on what options are supported by the node
6269 identified by Node. A description of valid Options for the local
6270 node of current OTP version can be found in the documentation of
6271 spawn_opt/4.
6272 spawn_opt(Module, Function, Args, Options) ->
6274 pid() | {pid(), reference()}
6275 Types:
6277 Module = module()
6279 Function = atom()
6280 Args = [term()]
6281 Options = [spawn_opt_option()]
6282 priority_level() = low | normal | high | max
6283 max_heap_size() =
6284 integer() >= 0 |
6285 #{size => integer() >= 0,
6286 kill => boolean(),
6287 error_logger => boolean()}
6288 message_queue_data() = off_heap | on_heap
6289 spawn_opt_option() =
6290 link | monitor |
6291 {priority, Level :: priority_level()} |
6292 {fullsweep_after, Number :: integer() >= 0} |
6293 {min_heap_size, Size :: integer() >= 0} |
6294 {min_bin_vheap_size, VSize :: integer() >= 0} |
6295 {max_heap_size, Size :: max_heap_size()} |
6296 {message_queue_data, MQD :: message_queue_data()}
6297 Works as spawn/3, except that an extra option list is specified
6299 when creating the process.
6300 If option monitor is specified, the newly created process is
6302 monitored, and both the pid and reference for the monitor are
6303 returned.
6304 Options:
6306 link:
6308 Sets a link to the parent process (like spawn_link/3 does).
6309 monitor:
6311 Monitors the new process (like monitor/2 does).
6312 {priority, Level}:
6314 Sets the priority of the new process. Equivalent to execut‐
6315 ing process_flag(priority, Level) in the start function of
6316 the new process, except that the priority is set before the
6317 process is selected for execution for the first time. For
6318 more information on priorities, see process_flag(priority,
6319 Level).
6320 {fullsweep_after, Number}:
6322 Useful only for performance tuning. Do not use this option
6323 unless you know that there is problem with execution times
6324 or memory consumption, and ensure that the option improves
6325 matters.
6326 The Erlang runtime system uses a generational garbage col‐
6328 lection scheme, using an "old heap" for data that has sur‐
6329 vived at least one garbage collection. When there is no more
6330 room on the old heap, a fullsweep garbage collection is
6331 done.
6332 Option fullsweep_after makes it possible to specify the max‐
6334 imum number of generational collections before forcing a
6335 fullsweep, even if there is room on the old heap. Setting
6336 the number to zero disables the general collection algo‐
6337 rithm, that is, all live data is copied at every garbage
6338 collection.
6339 A few cases when it can be useful to change fullsweep_after:
6341 * If binaries that are no longer used are to be thrown away
6343 as soon as possible. (Set Number to zero.)
6344 * A process that mostly have short-lived data is fullsweeped
6346 seldom or never, that is, the old heap contains mostly
6347 garbage. To ensure a fullsweep occasionally, set Number to
6348 a suitable value, such as 10 or 20.
6349 * In embedded systems with a limited amount of RAM and no
6351 virtual memory, you might want to preserve memory by set‐
6352 ting Number to zero. (The value can be set globally, see
6353 erlang:system_flag/2.)
6354 {min_heap_size, Size}:
6356 Useful only for performance tuning. Do not use this option
6357 unless you know that there is problem with execution times
6358 or memory consumption, and ensure that the option improves
6359 matters.
6360 Gives a minimum heap size, in words. Setting this value
6362 higher than the system default can speed up some processes
6363 because less garbage collection is done. However, setting a
6364 too high value can waste memory and slow down the system be‐
6365 cause of worse data locality. Therefore, use this option
6366 only for fine-tuning an application and to measure the exe‐
6367 cution time with various Size values.
6368 {min_bin_vheap_size, VSize}:
6370 Useful only for performance tuning. Do not use this option
6371 unless you know that there is problem with execution times
6372 or memory consumption, and ensure that the option improves
6373 matters.
6374 Gives a minimum binary virtual heap size, in words. Setting
6376 this value higher than the system default can speed up some
6377 processes because less garbage collection is done. However,
6378 setting a too high value can waste memory. Therefore, use
6379 this option only for fine-tuning an application and to mea‐
6380 sure the execution time with various VSize values.
6381 {max_heap_size, Size}:
6383 Sets the max_heap_size process flag. The default
6384 max_heap_size is determined by command-line argument +hmax
6385 in erl(1). For more information, see the documentation of
6386 process_flag(max_heap_size, Size).
6387 {message_queue_data, MQD}:
6389 Sets the value of the message_queue_data process flag. MQD
6390 can be either off_heap or on_heap. The default value of the
6391 message_queue_data process flag is determined by the com‐
6392 mand-line argument +hmqd in erl(1). For more information,
6393 see the documentation of process_flag(message_queue_data,
6394 MQD).
6395 spawn_opt(Node, Module, Function, Args, Options) ->
6397 pid() | {pid(), reference()}
6398 Types:
6400 Node = node()
6402 Module = module()
6403 Function = atom()
6404 Args = [term()]
6405 Options = [monitor | link | OtherOption]
6406 OtherOption = term()
6407 Returns the process identifier (pid) of a new process started by
6409 the application of Module:Function to Args on Node. If Node does
6410 not exist, a useless pid is returned. Otherwise works like
6411 spawn_opt/4.
6412 Valid options depends on what options are supported by the node
6414 identified by Node. A description of valid Options for the local
6415 node of current OTP version can be found in the documentation of
6416 spawn_opt/4.
6417 spawn_request(Fun) -> ReqId
6419 Types:
6421 Fun = function()
6423 ReqId = reference()
6424 The same as the call spawn_request(node(),Fun,[]). That is, a
6426 spawn request on the local node with no options.
6427 spawn_request(Fun, Options) -> ReqId
6429 Types:
6431 Fun = function()
6433 Option =
6434 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
6435 tion()
6436 ReplyTag = term()
6437 Reply = yes | no | error_only | success_only
6438 Options = [Option]
6439 ReqId = reference()
6440 The same as the call spawn_request(node(),Fun,Options). That is,
6442 a spawn request on the local node.
6443 spawn_request(Node, Fun) -> ReqId
6445 Types:
6447 Node = node()
6449 Fun = function()
6450 ReqId = reference()
6451 The same as the call spawn_request(Node,Fun,[]). That is, a
6453 spawn request with no options.
6454 spawn_request(Node, Fun, Options) -> ReqId
6456 Types:
6458 Node = node()
6460 Fun = function()
6461 Options = [Option]
6462 Option =
6463 monitor | link |
6464 {reply_tag, ReplyTag} |
6465 {reply, Reply} |
6466 OtherOption
6467 ReplyTag = term()
6468 Reply = yes | no | error_only | success_only
6469 OtherOption = term()
6470 ReqId = reference()
6471 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
6473 That is, a spawn request using the fun Fun of arity zero as en‐
6474 try point.
6475 This function will fail with a badarg exception if:
6477 * Node is not an atom.
6479 * Fun is not a fun of arity zero.
6481 * Options is not a proper list of terms.
6483 spawn_request(Module, Function, Args) -> ReqId
6485 Types:
6487 Module = module()
6489 Function = atom()
6490 Args = [term()]
6491 ReqId = reference()
6492 The same as the call spawn_request(node(),Module,Func‐
6494 tion,Args,[]). That is, a spawn request on the local node with
6495 no options.
6496 spawn_request(Node, Module, Function, Args) -> ReqId
6498 Types:
6500 Node = node()
6502 Module = module()
6503 Function = atom()
6504 Args = [term()]
6505 ReqId = reference()
6506 The same as the call spawn_request(Node,Module,Func‐
6508 tion,Args,[]). That is, a spawn request with no options.
6509 spawn_request(Module, Function, Args, Options) -> ReqId
6511 Types:
6513 Module = module()
6515 Function = atom()
6516 Args = [term()]
6517 Option =
6518 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
6519 tion()
6520 ReplyTag = term()
6521 Reply = yes | no | error_only | success_only
6522 Options = [Option]
6523 ReqId = reference()
6524 The same as the call spawn_request(node(),Module,Func‐
6526 tion,Args,Options). That is, a spawn request on the local node.
6527 spawn_request(Node, Module, Function, Args, Options) -> ReqId
6529 Types:
6531 Node = node()
6533 Module = module()
6534 Function = atom()
6535 Args = [term()]
6536 Options = [Option]
6537 Option =
6538 monitor | link |
6539 {reply_tag, ReplyTag} |
6540 {reply, Reply} |
6541 OtherOption
6542 ReplyTag = term()
6543 Reply = yes | no | error_only | success_only
6544 OtherOption = term()
6545 ReqId = reference()
6546 Asynchronously send a spawn request. Returns a request identi‐
6548 fier ReqId.
6549 If the spawn operation succeeds, a new process is created on the
6551 node identified by Node. When a spawn operation succeeds, the
6552 caller will by default be sent a message on the form {ReplyTag,
6553 ReqId, ok, Pid} where Pid is the process identifier of the newly
6554 created process. Such a message is referred to as a success mes‐
6555 sage below in the text. ReplyTag is by default the atom
6556 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
6557 The new process is started by the application of Module:Function
6558 to Args.
6559 The spawn operation fails either if creation of a new process
6561 failed or if the spawn operation was interrupted by a connection
6562 failure. When a spawn operation fails, the caller will by de‐
6563 fault be sent a message on the form {ReplyTag, ReqId, error,
6564 Reason} where Reason is the error reason. Such a message is re‐
6565 ferred to as an error message below in the text. Currently the
6566 following spawn error Reasons are defined, but other reasons can
6567 appear at any time without prior notice:
6568 badopt:
6570 An invalid Option was passed as argument. Note that differ‐
6571 ent runtime systems may support different options.
6572 notsup:
6574 The node identified by Node does not support spawn opera‐
6575 tions issued by spawn_request().
6576 noconnection:
6578 Failure to set up a connection to the node identified by
6579 Node or the connection to that node was lost during the
6580 spawn operation. In the case the connection was lost, a
6581 process may or may not have been created.
6582 system_limit:
6584 Could not create a new process due to that some system limit
6585 was reached. Typically the process table was full.
6586 Valid Options:
6588 monitor:
6590 In the absence of spawn operation failures, atomically sets
6591 up a monitor to the newly created process. That is, as if
6592 the calling process had called monitor(process, Pid) where
6593 Pid is the process identifier of the newly created process.
6594 The ReqId returned by spawn_request() is also used as moni‐
6595 tor reference as if it was returned from monitor(process,
6596 Pid).
6597 The monitor will not be activated for the calling process
6599 until the spawn operation has succeeded. The monitor can not
6600 be demonitored before the operation has succeeded. A 'DOWN'
6601 message for the corresponding monitor is guaranteed not to
6602 be delivered before a success message that corresponds to
6603 the spawn operation. If the spawn operation fails, no 'DOWN'
6604 message will be delivered.
6605 If the connection between the nodes involved in the spawn
6607 operation is lost during the spawn operation, the spawn op‐
6608 eration will fail with an error reason of noconnection. A
6609 new process may or may not have been created.
6610 link:
6612 In absence of spawn operation failures, atomically sets up a
6613 link between the calling process and the newly created
6614 process. That is, as if the calling process had called
6615 link(Pid) where Pid is the process identifier of the newly
6616 created process.
6617 The link will not be activated for the calling process until
6619 the spawn operation has succeeded. The link can not be re‐
6620 moved before the operation has succeeded. An exit signal due
6621 to the link is guaranteed not to be delivered before a suc‐
6622 cess message that corresponds to the spawn operation. If
6623 the spawn operation fails, no exit signal due to the link
6624 will be delivered to the caller of spawn_request().
6625 If the connection between the nodes involved in the spawn
6627 operation is lost during the spawn operation, the spawn op‐
6628 eration will fail with an error reason of noconnection. A
6629 new process may or may not have been created. If it has been
6630 created, it will be delivered an exit signal with an exit
6631 reason of noconnection.
6632 {reply, Reply}:
6634 Valid Reply values:
6635 yes:
6637 A spawn reply message will be sent to the caller regard‐
6638 less of whether the operation succeeds or not. If the call
6639 to spawn_request() returns without raising an exception
6640 and the reply option is set to yes, the caller is guaran‐
6641 teed to be delivered either a success message or an error
6642 message . The reply option is by default set to yes.
6643 no:
6645 No spawn reply message will be sent to the caller when the
6646 spawn operation completes. This regardless of whether the
6647 operation succeeds or not.
6648 error_only:
6650 No spawn reply message will be sent to the caller if the
6651 spawn operation succeeds, but an error message will be
6652 sent to the caller if the operation fails.
6653 success_only:
6655 No spawn reply message will be sent to the caller if the
6656 spawn operation fails, but a success message will be sent
6657 to the caller if the operation succeeds.
6658 {reply_tag, ReplyTag}:
6660 Sets the reply tag to ReplyTag in the reply message. That
6661 is, in the success or error message that is sent to the
6662 caller due to the spawn operation. The default reply tag is
6663 the atom spawn_reply.
6664 OtherOption:
6666 Other valid options depends on what options are supported by
6667 the node identified by Node. A description of other valid
6668 Options for the local node of current OTP version can be
6669 found in the documentation of spawn_opt/4.
6670 This function will fail with a badarg exception if:
6672 * Node is not an atom.
6674 * Module is not an atom.
6676 * Function is not an atom.
6678 * Args is not a proper list of terms.
6680 * Options is not a proper list of terms.
6682 Note that not all individual Options are checked when the spawn
6684 request is sent. Some Options can only be checked on reception
6685 of the request. Therefore an invalid option does not cause a
6686 badarg exception, but will cause the spawn operation to fail
6687 with an error reason of badopt.
6688 A spawn request can be abandoned by calling spawn_request_aban‐
6690 don/1.
6691 spawn_request_abandon(ReqId :: reference()) -> boolean()
6693 Abandon a previously issued spawn request. ReqId corresponds to
6695 a request identifier previously returned by spawn_request() in a
6696 call from current process. That is, only the process that has
6697 made the request can abandon the request.
6698 A spawn request can only be successfully abandoned until the
6700 spawn request has completed. When a spawn request has been suc‐
6701 cessfully abandoned, the caller will not be effected by future
6702 direct effects of the spawn request itself. For example, it will
6703 not receive a spawn reply message. The request is however not
6704 withdrawn, so a new process may or may not be created due to the
6705 request. If a new process is created after the spawn request was
6706 abandoned, no monitors nor links will be set up to the caller of
6707 spawn_request_abandon/1 due to the spawn request. If the spawn
6708 request included the link option, the process created due to
6709 this request will be sent an exit signal from its parent with
6710 the exit reason abandoned when it is detected that the spawn op‐
6711 eration has succeeded.
6712 Note:
6714 A process created due to a spawn request that has been abandoned
6715 may communicate with its parent as any other process. It is only
6716 the direct effects on the parent of the actual spawn request,
6717 that will be canceled by abandoning a spawn request.
6718 Return values:
6721 true:
6723 The spawn request was successfully abandoned.
6724 false:
6726 No spawn request was abandoned. The ReqId request identifier
6727 did not correspond to an outstanding spawn request issued by
6728 the calling process. The reason for this is either:
6729 * ReqId corresponds to a spawn request previoulsy made by
6731 the calling process. The spawn operation has completed and
6732 a spawn reply has already been delivered to the calling
6733 process unless the spawn reply was disabled in the re‐
6734 quest.
6735 * ReqId does not correspond to a spawn request that has been
6737 made by the calling process.
6738 This function fail with a badarg exception if ReqId is not a
6740 reference.
6741 split_binary(Bin, Pos) -> {binary(), binary()}
6743 Types:
6745 Bin = binary()
6747 Pos = integer() >= 0
6748 0..byte_size(Bin)
6749 Returns a tuple containing the binaries that are the result of
6751 splitting Bin into two parts at position Pos. This is not a de‐
6752 structive operation. After the operation, there are three bina‐
6753 ries altogether. Example:
6754 > B = list_to_binary("0123456789").
6756 <<"0123456789">>
6757 > byte_size(B).
6758 10
6759 > {B1, B2} = split_binary(B,3).
6760 {<<"012">>,<<"3456789">>}
6761 > byte_size(B1).
6762 3
6763 > byte_size(B2).
6764 7
6765 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6767 Types:
6769 Time = integer() >= 0
6771 Dest = pid() | atom()
6772 Msg = term()
6773 TimerRef = reference()
6774 Starts a timer. The same as calling erlang:start_timer(Time,
6776 Dest, Msg, []).
6777 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6779 Types:
6781 Time = integer()
6783 Dest = pid() | atom()
6784 Msg = term()
6785 Options = [Option]
6786 Abs = boolean()
6787 Option = {abs, Abs}
6788 TimerRef = reference()
6789 Starts a timer. When the timer expires, the message {timeout,
6791 TimerRef, Msg} is sent to the process identified by Dest.
6792 Options:
6794 {abs, false}:
6796 This is the default. It means the Time value is interpreted
6797 as a time in milliseconds relative current Erlang monotonic
6798 time.
6799 {abs, true}:
6801 Absolute Time value. The Time value is interpreted as an ab‐
6802 solute Erlang monotonic time in milliseconds.
6803 More Options can be added in the future.
6805 The absolute point in time, the timer is set to expire on, must
6807 be in the interval [erlang:system_info(start_time), erlang:sys‐
6808 tem_info(end_time)]. If a relative time is specified, the Time
6809 value is not allowed to be negative.
6810 If Dest is a pid(), it must be a pid() of a process created on
6812 the current runtime system instance. This process has either
6813 terminated or not. If Dest is an atom(), it is interpreted as
6814 the name of a locally registered process. The process referred
6815 to by the name is looked up at the time of timer expiration. No
6816 error is returned if the name does not refer to a process.
6817 If Dest is a pid(), the timer is automatically canceled if the
6819 process referred to by the pid() is not alive, or if the process
6820 exits. This feature was introduced in ERTS 5.4.11. Notice that
6821 timers are not automatically canceled when Dest is an atom().
6822 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
6824 lang:read_timer/2.
6825 Failure: badarg if the arguments do not satisfy the requirements
6827 specified here.
6828 statistics(Item :: active_tasks) -> [ActiveTasks]
6830 Types:
6832 ActiveTasks = integer() >= 0
6834 Returns the same as statistics(active_tasks_all) with the excep‐
6836 tion that no information about the dirty IO run queue and its
6837 associated schedulers is part of the result. That is, only tasks
6838 that are expected to be CPU bound are part of the result.
6839 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6841 Types:
6843 ActiveTasks = integer() >= 0
6845 Returns a list where each element represents the amount of ac‐
6847 tive processes and ports on each run queue and its associated
6848 schedulers. That is, the number of processes and ports that are
6849 ready to run, or are currently running. Values for normal run
6850 queues and their associated schedulers are located first in the
6851 resulting list. The first element corresponds to scheduler num‐
6852 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6853 ment with the value for the dirty CPU run queue and its associ‐
6854 ated dirty CPU schedulers follow and then as last element the
6855 value for the the dirty IO run queue and its associated dirty IO
6856 schedulers follow. The information is not gathered atomically.
6857 That is, the result is not necessarily a consistent snapshot of
6858 the state, but instead quite efficiently gathered.
6859 Note:
6861 Each normal scheduler has one run queue that it manages. If
6862 dirty schedulers schedulers are supported, all dirty CPU sched‐
6863 ulers share one run queue, and all dirty IO schedulers share one
6864 run queue. That is, we have multiple normal run queues, one
6865 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
6866 grate between the different types of run queues. Only work in
6867 normal run queues can migrate to other normal run queues. This
6868 has to be taken into account when evaluating the result.
6869 See also statistics(total_active_tasks), statis‐
6872 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6873 tistics(total_run_queue_lengths), and statistics(to‐
6874 tal_run_queue_lengths_all).
6875 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6877 Types:
6879 ContextSwitches = integer() >= 0
6881 Returns the total number of context switches since the system
6883 started.
6884 statistics(Item :: exact_reductions) ->
6886 {Total_Exact_Reductions,
6887 Exact_Reductions_Since_Last_Call}
6888 Types:
6890 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6892 integer() >= 0
6893 Returns the number of exact reductions.
6895 Note:
6897 statistics(exact_reductions) is a more expensive operation than
6898 statistics(reductions).
6899 statistics(Item :: garbage_collection) ->
6902 {Number_of_GCs, Words_Reclaimed, 0}
6903 Types:
6905 Number_of_GCs = Words_Reclaimed = integer() >= 0
6907 Returns information about garbage collection, for example:
6909 > statistics(garbage_collection).
6911 {85,23961,0}
6912 This information can be invalid for some implementations.
6914 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6916 Types:
6918 Input = Output = integer() >= 0
6920 Returns Input, which is the total number of bytes received
6922 through ports, and Output, which is the total number of bytes
6923 output to ports.
6924 statistics(Item :: microstate_accounting) ->
6926 [MSAcc_Thread] | undefined
6927 Types:
6929 MSAcc_Thread =
6931 #{type := MSAcc_Thread_Type,
6932 id := MSAcc_Thread_Id,
6933 counters := MSAcc_Counters}
6934 MSAcc_Thread_Type =
6935 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
6936 poll | scheduler
6937 MSAcc_Thread_Id = integer() >= 0
6938 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6939 MSAcc_Thread_State =
6940 alloc | aux | bif | busy_wait | check_io | emulator | ets
6941 |
6942 gc | gc_fullsweep | nif | other | port | send | sleep |
6943 timers
6944 Microstate accounting can be used to measure how much time the
6946 Erlang runtime system spends doing various tasks. It is designed
6947 to be as lightweight as possible, but some overhead exists when
6948 this is enabled. Microstate accounting is meant to be a profil‐
6949 ing tool to help finding performance bottlenecks. To
6950 start/stop/reset microstate accounting, use system flag mi‐
6951 crostate_accounting.
6952 statistics(microstate_accounting) returns a list of maps repre‐
6954 senting some of the OS threads within ERTS. Each map contains
6955 type and id fields that can be used to identify what thread it
6956 is, and also a counters field that contains data about how much
6957 time has been spent in the various states.
6958 Example:
6960 > erlang:statistics(microstate_accounting).
6962 [#{counters => #{aux => 1899182914,
6963 check_io => 2605863602,
6964 emulator => 45731880463,
6965 gc => 1512206910,
6966 other => 5421338456,
6967 port => 221631,
6968 sleep => 5150294100},
6969 id => 1,
6970 type => scheduler}|...]
6971 The time unit is the same as returned by os:perf_counter/0. So,
6973 to convert it to milliseconds, you can do something like this:
6974 lists:map(
6976 fun(#{ counters := Cnt } = M) ->
6977 MsCnt = maps:map(fun(_K, PerfCount) ->
6978 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6979 end, Cnt),
6980 M#{ counters := MsCnt }
6981 end, erlang:statistics(microstate_accounting)).
6982 Notice that these values are not guaranteed to be the exact time
6984 spent in each state. This is because of various optimisation
6985 done to keep the overhead as small as possible.
6986 MSAcc_Thread_Types:
6988 scheduler:
6990 The main execution threads that do most of the work. See erl
6991 +S for more details.
6992 dirty_cpu_scheduler:
6994 The threads for long running cpu intensive work. See erl
6995 +SDcpu for more details.
6996 dirty_io_scheduler:
6998 The threads for long running I/O work. See erl +SDio for
6999 more details.
7000 async:
7002 Async threads are used by various linked-in drivers (mainly
7003 the file drivers) do offload non-CPU intensive work. See erl
7004 +A for more details.
7005 aux:
7007 Takes care of any work that is not specifically assigned to
7008 a scheduler.
7009 poll:
7011 Does the IO polling for the emulator. See erl +IOt for more
7012 details.
7013 The following MSAcc_Thread_States are available. All states are
7015 exclusive, meaning that a thread cannot be in two states at
7016 once. So, if you add the numbers of all counters in a thread,
7017 you get the total runtime for that thread.
7018 aux:
7020 Time spent handling auxiliary jobs.
7021 check_io:
7023 Time spent checking for new I/O events.
7024 emulator:
7026 Time spent executing Erlang processes.
7027 gc:
7029 Time spent doing garbage collection. When extra states are
7030 enabled this is the time spent doing non-fullsweep garbage
7031 collections.
7032 other:
7034 Time spent doing unaccounted things.
7035 port:
7037 Time spent executing ports.
7038 sleep:
7040 Time spent sleeping.
7041 More fine-grained MSAcc_Thread_States can be added through con‐
7043 figure (such as ./configure --with-microstate-accounting=extra).
7044 Enabling these states causes performance degradation when mi‐
7045 crostate accounting is turned off and increases the overhead
7046 when it is turned on.
7047 alloc:
7049 Time spent managing memory. Without extra states this time
7050 is spread out over all other states.
7051 bif:
7053 Time spent in BIFs. Without extra states this time is part
7054 of the emulator state.
7055 busy_wait:
7057 Time spent busy waiting. This is also the state where a
7058 scheduler no longer reports that it is active when using
7059 statistics(scheduler_wall_time). So, if you add all other
7060 states but this and sleep, and then divide that by all time
7061 in the thread, you should get something very similar to the
7062 scheduler_wall_time fraction. Without extra states this time
7063 is part of the other state.
7064 ets:
7066 Time spent executing ETS BIFs. Without extra states this
7067 time is part of the emulator state.
7068 gc_full:
7070 Time spent doing fullsweep garbage collection. Without extra
7071 states this time is part of the gc state.
7072 nif:
7074 Time spent in NIFs. Without extra states this time is part
7075 of the emulator state.
7076 send:
7078 Time spent sending messages (processes only). Without extra
7079 states this time is part of the emulator state.
7080 timers:
7082 Time spent managing timers. Without extra states this time
7083 is part of the other state.
7084 The utility module msacc(3) can be used to more easily analyse
7086 these statistics.
7087 Returns undefined if system flag microstate_accounting is turned
7089 off.
7090 The list of thread information is unsorted and can appear in
7092 different order between calls.
7093 Note:
7095 The threads and states are subject to change without any prior
7096 notice.
7097 statistics(Item :: reductions) ->
7100 {Total_Reductions, Reductions_Since_Last_Call}
7101 Types:
7103 Total_Reductions = Reductions_Since_Last_Call = integer() >=
7105 0
7106 Returns information about reductions, for example:
7108 > statistics(reductions).
7110 {2046,11}
7111 Note:
7113 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
7114 reductions performed in current time slices of currently sched‐
7115 uled processes. If an exact value is wanted, use statistics(ex‐
7116 act_reductions).
7117 statistics(Item :: run_queue) -> integer() >= 0
7120 Returns the total length of all normal and dirty CPU run queues.
7122 That is, queued work that is expected to be CPU bound. The in‐
7123 formation is gathered atomically. That is, the result is a con‐
7124 sistent snapshot of the state, but this operation is much more
7125 expensive compared to statistics(total_run_queue_lengths), espe‐
7126 cially when a large amount of schedulers is used.
7127 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
7129 Types:
7131 RunQueueLength = integer() >= 0
7133 Returns the same as statistics(run_queue_lengths_all) with the
7135 exception that no information about the dirty IO run queue is
7136 part of the result. That is, only run queues with work that is
7137 expected to be CPU bound is part of the result.
7138 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
7140 Types:
7142 RunQueueLength = integer() >= 0
7144 Returns a list where each element represents the amount of pro‐
7146 cesses and ports ready to run for each run queue. Values for
7147 normal run queues are located first in the resulting list. The
7148 first element corresponds to the normal run queue of scheduler
7149 number 1 and so on. If support for dirty schedulers exist, val‐
7150 ues for the dirty CPU run queue and the dirty IO run queue fol‐
7151 low (in that order) at the end. The information is not gathered
7152 atomically. That is, the result is not necessarily a consistent
7153 snapshot of the state, but instead quite efficiently gathered.
7154 Note:
7156 Each normal scheduler has one run queue that it manages. If
7157 dirty schedulers schedulers are supported, all dirty CPU sched‐
7158 ulers share one run queue, and all dirty IO schedulers share one
7159 run queue. That is, we have multiple normal run queues, one
7160 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7161 grate between the different types of run queues. Only work in
7162 normal run queues can migrate to other normal run queues. This
7163 has to be taken into account when evaluating the result.
7164 See also statistics(run_queue_lengths), statistics(to‐
7167 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
7168 statistics(active_tasks), statistics(active_tasks_all), and sta‐
7169 tistics(total_active_tasks), statistics(total_active_tasks_all).
7170 statistics(Item :: runtime) ->
7172 {Total_Run_Time, Time_Since_Last_Call}
7173 Types:
7175 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
7177 Returns information about runtime, in milliseconds.
7179 This is the sum of the runtime for all threads in the Erlang
7181 runtime system and can therefore be greater than the wall clock
7182 time.
7183 Warning:
7185 This value might wrap due to limitations in the underlying func‐
7186 tionality provided by the operating system that is used.
7187 Example:
7190 > statistics(runtime).
7192 {1690,1620}
7193 statistics(Item :: scheduler_wall_time) ->
7195 [{SchedulerId, ActiveTime, TotalTime}] | undefined
7196 Types:
7198 SchedulerId = integer() >= 1
7200 ActiveTime = TotalTime = integer() >= 0
7201 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
7203 Time}, where SchedulerId is an integer ID of the scheduler, Ac‐
7204 tiveTime is the duration the scheduler has been busy, and Total‐
7205 Time is the total time duration since scheduler_wall_time acti‐
7206 vation for the specific scheduler. Note that activation time can
7207 differ significantly between schedulers. Currently dirty sched‐
7208 ulers are activated at system start while normal schedulers are
7209 activated some time after the scheduler_wall_time functionality
7210 is enabled. The time unit is undefined and can be subject to
7211 change between releases, OSs, and system restarts. sched‐
7212 uler_wall_time is only to be used to calculate relative values
7213 for scheduler utilization. ActiveTime can never exceed Total‐
7214 Time.
7215 The definition of a busy scheduler is when it is not idle and is
7217 not scheduling (selecting) a process or port, that is:
7218 * Executing process code
7220 * Executing linked-in driver or NIF code
7222 * Executing BIFs, or any other runtime handling
7224 * Garbage collecting
7226 * Handling any other memory management
7228 Notice that a scheduler can also be busy even if the OS has
7230 scheduled out the scheduler thread.
7231 Returns undefined if system flag scheduler_wall_time is turned
7233 off.
7234 The list of scheduler information is unsorted and can appear in
7236 different order between calls.
7237 As of ERTS version 9.0, also dirty CPU schedulers will be in‐
7239 cluded in the result. That is, all scheduler threads that are
7240 expected to handle CPU bound work. If you also want information
7241 about dirty I/O schedulers, use statistics(sched‐
7242 uler_wall_time_all) instead.
7243 Normal schedulers will have scheduler identifiers in the range 1
7245 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
7246 schedulers will have scheduler identifiers in the range er‐
7247 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
7248 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
7249 Note:
7251 The different types of schedulers handle specific types of jobs.
7252 Every job is assigned to a specific scheduler type. Jobs can mi‐
7253 grate between different schedulers of the same type, but never
7254 between schedulers of different types. This fact has to be taken
7255 under consideration when evaluating the result returned.
7256 Using scheduler_wall_time to calculate scheduler utilization:
7259 > erlang:system_flag(scheduler_wall_time, true).
7261 false
7262 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
7263 ok
7264 Some time later the user takes another snapshot and calculates
7266 scheduler utilization per scheduler, for example:
7267 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
7269 ok
7270 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
7271 [{1,0.9743474730177548},
7272 {2,0.9744843782751444},
7273 {3,0.9995902361669045},
7274 {4,0.9738012596572161},
7275 {5,0.9717956667018103},
7276 {6,0.9739235846420741},
7277 {7,0.973237033077876},
7278 {8,0.9741297293248656}]
7279 Using the same snapshots to calculate a total scheduler utiliza‐
7281 tion:
7282 > {A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) -> {Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), TotalSchedulerUtilization = A/T.
7284 0.9769136803764825
7285 Total scheduler utilization will equal 1.0 when all schedulers
7287 have been active all the time between the two measurements.
7288 Another (probably more) useful value is to calculate total
7290 scheduler utilization weighted against maximum amount of avail‐
7291 able CPU time:
7292 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
7294 0.9769136803764825
7295 This weighted scheduler utilization will reach 1.0 when sched‐
7297 ulers are active the same amount of time as maximum available
7298 CPU time. If more schedulers exist than available logical pro‐
7299 cessors, this value may be greater than 1.0.
7300 As of ERTS version 9.0, the Erlang runtime system will as de‐
7302 fault have more schedulers than logical processors. This due to
7303 the dirty schedulers.
7304 Note:
7306 scheduler_wall_time is by default disabled. To enable it, use
7307 erlang:system_flag(scheduler_wall_time, true).
7308 statistics(Item :: scheduler_wall_time_all) ->
7311 [{SchedulerId, ActiveTime, TotalTime}] | undefined
7312 Types:
7314 SchedulerId = integer() >= 1
7316 ActiveTime = TotalTime = integer() >= 0
7317 The same as statistics(scheduler_wall_time), except that it also
7319 include information about all dirty I/O schedulers.
7320 Dirty IO schedulers will have scheduler identifiers in the range
7322 erlang:system_info(schedulers) + erlang:sys‐
7323 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
7324 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
7325 + erlang:system_info(dirty_io_schedulers).
7326 Note:
7328 Note that work executing on dirty I/O schedulers are expected to
7329 mainly wait for I/O. That is, when you get high scheduler uti‐
7330 lization on dirty I/O schedulers, CPU utilization is not ex‐
7331 pected to be high due to this work.
7332 statistics(Item :: total_active_tasks) -> ActiveTasks
7335 Types:
7337 ActiveTasks = integer() >= 0
7339 The same as calling lists:sum(statistics(active_tasks)), but
7341 more efficient.
7342 statistics(Item :: total_active_tasks_all) -> ActiveTasks
7344 Types:
7346 ActiveTasks = integer() >= 0
7348 The same as calling lists:sum(statistics(active_tasks_all)), but
7350 more efficient.
7351 statistics(Item :: total_run_queue_lengths) ->
7353 TotalRunQueueLengths
7354 Types:
7356 TotalRunQueueLengths = integer() >= 0
7358 The same as calling lists:sum(statistics(run_queue_lengths)),
7360 but more efficient.
7361 statistics(Item :: total_run_queue_lengths_all) ->
7363 TotalRunQueueLengths
7364 Types:
7366 TotalRunQueueLengths = integer() >= 0
7368 The same as calling lists:sum(statis‐
7370 tics(run_queue_lengths_all)), but more efficient.
7371 statistics(Item :: wall_clock) ->
7373 {Total_Wallclock_Time,
7374 Wallclock_Time_Since_Last_Call}
7375 Types:
7377 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
7379 ger() >= 0
7380 Returns information about wall clock. wall_clock can be used in
7382 the same manner as runtime, except that real time is measured as
7383 opposed to runtime or CPU time.
7384 erlang:suspend_process(Suspendee) -> true
7386 Types:
7388 Suspendee = pid()
7390 Suspends the process identified by Suspendee. The same as call‐
7392 ing erlang:suspend_process(Suspendee, []).
7393 Warning:
7395 This BIF is intended for debugging only.
7396 erlang:suspend_process(Suspendee, OptList) -> boolean()
7399 Types:
7401 Suspendee = pid()
7403 OptList = [Opt]
7404 Opt = unless_suspending | asynchronous | {asynchronous,
7405 term()}
7406 Increases the suspend count on the process identified by Sus‐
7408 pendee and puts it in the suspended state if it is not already
7409 in that state. A suspended process is not scheduled for execu‐
7410 tion until the process has been resumed.
7411 A process can be suspended by multiple processes and can be sus‐
7413 pended multiple times by a single process. A suspended process
7414 does not leave the suspended state until its suspend count
7415 reaches zero. The suspend count of Suspendee is decreased when
7416 erlang:resume_process(Suspendee) is called by the same process
7417 that called erlang:suspend_process(Suspendee). All increased
7418 suspend counts on other processes acquired by a process are au‐
7419 tomatically decreased when the process terminates.
7420 Options (Opts):
7422 asynchronous:
7424 A suspend request is sent to the process identified by Sus‐
7425 pendee. Suspendee eventually suspends unless it is resumed
7426 before it could suspend. The caller of erlang:sus‐
7427 pend_process/2 returns immediately, regardless of whether
7428 Suspendee has suspended yet or not. The point in time when
7429 Suspendee suspends cannot be deduced from other events in
7430 the system. It is only guaranteed that Suspendee eventually
7431 suspends (unless it is resumed). If no asynchronous options
7432 has been passed, the caller of erlang:suspend_process/2 is
7433 blocked until Suspendee has suspended.
7434 {asynchronous, ReplyTag}:
7436 A suspend request is sent to the process identified by Sus‐
7437 pendee. When the suspend request has been processed, a reply
7438 message is sent to the caller of this function. The reply is
7439 on the form {ReplyTag, State} where State is either:
7440 exited:
7442 Suspendee has exited.
7443 suspended:
7445 Suspendee is now suspended.
7446 not_suspended:
7448 Suspendee is not suspended. This can only happen when the
7449 process that issued this request, have called re‐
7450 sume_process(Suspendee) before getting the reply.
7451 Appart from the reply message, the {asynchronous, ReplyTag}
7453 option behaves exactly the same as the asynchronous option
7454 without reply tag.
7455 unless_suspending:
7457 The process identified by Suspendee is suspended unless the
7458 calling process already is suspending Suspendee. If un‐
7459 less_suspending is combined with option asynchronous, a sus‐
7460 pend request is sent unless the calling process already is
7461 suspending Suspendee or if a suspend request already has
7462 been sent and is in transit. If the calling process already
7463 is suspending Suspendee, or if combined with option asyn‐
7464 chronous and a send request already is in transit, false is
7465 returned and the suspend count on Suspendee remains un‐
7466 changed.
7467 If the suspend count on the process identified by Suspendee is
7469 increased, true is returned, otherwise false.
7470 Warning:
7472 This BIF is intended for debugging only.
7473 Warning:
7476 You can easily create deadlocks if processes suspends each other
7477 (directly or in circles). In ERTS versions prior to ERTS version
7478 10.0, the runtime system prevented such deadlocks, but this pre‐
7479 vention has now been removed due to performance reasons.
7480 Failures:
7483 badarg:
7485 If Suspendee is not a process identifier.
7486 badarg:
7488 If the process identified by Suspendee is the same process
7489 as the process calling erlang:suspend_process/2.
7490 badarg:
7492 If the process identified by Suspendee is not alive.
7493 badarg:
7495 If the process identified by Suspendee resides on another
7496 node.
7497 badarg:
7499 If OptList is not a proper list of valid Opts.
7500 system_limit:
7502 If the process identified by Suspendee has been suspended
7503 more times by the calling process than can be represented by
7504 the currently used internal data structures. The system
7505 limit is greater than 2,000,000,000 suspends and will never
7506 be lower.
7507 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
7509 Types:
7511 Depth = OldDepth = integer() >= 0
7513 Sets the maximum depth of call stack back-traces in the exit
7515 reason element of 'EXIT' tuples. The flag also limits the stack‐
7516 trace depth returned by process_info item current_stacktrace.
7517 Returns the old value of the flag.
7519 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
7521 OldCpuTopology
7522 Types:
7524 CpuTopology = OldCpuTopology = cpu_topology()
7526 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7527 level_entry() =
7528 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7529 {LevelTag :: level_tag(),
7530 InfoList :: info_list(),
7531 SubLevel :: sub_level()}
7532 level_tag() = core | node | processor | thread
7533 sub_level() =
7534 [LevelEntry :: level_entry()] |
7535 (LogicalCpuId :: {logical, integer() >= 0})
7536 info_list() = []
7537 Warning:
7539 This argument is deprecated. Instead of using this argument, use
7540 command-line argument +sct in erl(1).
7541 When this argument is removed, a final CPU topology to use is
7543 determined at emulator boot time.
7544 Sets the user-defined CpuTopology. The user-defined CPU topology
7547 overrides any automatically detected CPU topology. By passing
7548 undefined as CpuTopology, the system reverts to the CPU topology
7549 automatically detected. The returned value equals the value re‐
7550 turned from erlang:system_info(cpu_topology) before the change
7551 was made.
7552 Returns the old value of the flag.
7554 The CPU topology is used when binding schedulers to logical pro‐
7556 cessors. If schedulers are already bound when the CPU topology
7557 is changed, the schedulers are sent a request to rebind accord‐
7558 ing to the new CPU topology.
7559 The user-defined CPU topology can also be set by passing com‐
7561 mand-line argument +sct to erl(1).
7562 For information on type CpuTopology and more, see erlang:sys‐
7564 tem_info(cpu_topology) as well as command-line flags +sct and
7565 +sbt in erl(1).
7566 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
7568 DirtyCPUSchedulersOnline) ->
7569 OldDirtyCPUSchedulersOnline
7570 Types:
7572 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
7574 teger() >= 1
7575 Sets the number of dirty CPU schedulers online. Range is 1 <=
7577 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
7578 return values of erlang:system_info(dirty_cpu_schedulers) and
7579 erlang:system_info(schedulers_online).
7580 Returns the old value of the flag.
7582 The number of dirty CPU schedulers online can change if the num‐
7584 ber of schedulers online changes. For example, if 12 schedulers
7585 and 6 dirty CPU schedulers are online, and system_flag/2 is used
7586 to set the number of schedulers online to 6, then the number of
7587 dirty CPU schedulers online is automatically decreased by half
7588 as well, down to 3. Similarly, the number of dirty CPU sched‐
7589 ulers online increases proportionally to increases in the number
7590 of schedulers online.
7591 For more information, see erlang:system_info(dirty_cpu_sched‐
7593 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
7594 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
7596 ok | notsup
7597 Types:
7599 Alloc = F = atom()
7601 V = integer()
7602 Sets system flags for erts_alloc(3). Alloc is the allocator to
7604 affect, for example binary_alloc. F is the flag to change and V
7605 is the new value.
7606 Only a subset of all erts_alloc flags can be changed at run
7608 time. This subset is currently only the flag sbct.
7609 Returns ok if the flag was set or notsup if not supported by
7611 erts_alloc.
7612 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
7614 Types:
7616 Number = OldNumber = integer() >= 0
7618 Sets system flag fullsweep_after. Number is a non-negative inte‐
7620 ger indicating how many times generational garbage collections
7621 can be done without forcing a fullsweep collection. The value
7622 applies to new processes, while processes already running are
7623 not affected.
7624 Returns the old value of the flag.
7626 In low-memory systems (especially without virtual memory), set‐
7628 ting the value to 0 can help to conserve memory.
7629 This value can also be set through (OS) environment variable
7631 ERL_FULLSWEEP_AFTER.
7632 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7634 OldState
7635 Types:
7637 Action = true | false | reset
7639 OldState = true | false
7640 Turns on/off microstate accounting measurements. When passing
7642 reset, all counters are reset to 0.
7643 For more information see statistics(microstate_accounting).
7645 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7647 OldMinHeapSize
7648 Types:
7650 MinHeapSize = OldMinHeapSize = integer() >= 0
7652 Sets the default minimum heap size for processes. The size is
7654 specified in words. The new min_heap_size effects only processes
7655 spawned after the change of min_heap_size has been made.
7656 min_heap_size can be set for individual processes by using
7657 spawn_opt/4 or process_flag/2.
7658 Returns the old value of the flag.
7660 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7662 OldMinBinVHeapSize
7663 Types:
7665 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7667 Sets the default minimum binary virtual heap size for processes.
7669 The size is specified in words. The new min_bin_vhheap_size ef‐
7670 fects only processes spawned after the change of
7671 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7672 for individual processes by using spawn_opt/2,3,4 or
7673 process_flag/2.
7674 Returns the old value of the flag.
7676 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7678 OldMaxHeapSize
7679 Types:
7681 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7683 max_heap_size() =
7684 integer() >= 0 |
7685 #{size => integer() >= 0,
7686 kill => boolean(),
7687 error_logger => boolean()}
7688 Sets the default maximum heap size settings for processes. The
7690 size is specified in words. The new max_heap_size effects only
7691 processes spawned efter the change has been made. max_heap_size
7692 can be set for individual processes using spawn_opt/2,3,4 or
7693 process_flag/2.
7694 Returns the old value of the flag.
7696 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7698 OldBlockState
7699 Types:
7701 BlockState = block | unblock | block_normal | unblock_normal
7703 OldBlockState = blocked | disabled | enabled
7704 If multi-scheduling is enabled, more than one scheduler thread
7706 is used by the emulator. Multi-scheduling can be blocked in two
7707 different ways. Either all schedulers but one is blocked, or all
7708 normal schedulers but one is blocked. When only normal sched‐
7709 ulers are blocked, dirty schedulers are free to continue to
7710 schedule processes.
7711 If BlockState =:= block, multi-scheduling is blocked. That is,
7713 one and only one scheduler thread will execute. If BlockState
7714 =:= unblock and no one else blocks multi-scheduling, and this
7715 process has blocked only once, multi-scheduling is unblocked.
7716 If BlockState =:= block_normal, normal multi-scheduling is
7718 blocked. That is, only one normal scheduler thread will execute,
7719 but multiple dirty schedulers can execute. If BlockState =:= un‐
7720 block_normal and no one else blocks normal multi-scheduling, and
7721 this process has blocked only once, normal multi-scheduling is
7722 unblocked.
7723 One process can block multi-scheduling and normal multi-schedul‐
7725 ing multiple times. If a process has blocked multiple times, it
7726 must unblock exactly as many times as it has blocked before it
7727 has released its multi-scheduling block. If a process that has
7728 blocked multi-scheduling or normal multi-scheduling exits, it
7729 automatically releases its blocking of multi-scheduling and nor‐
7730 mal multi-scheduling.
7731 The return values are disabled, blocked, blocked_normal, or en‐
7733 abled. The returned value describes the state just after the
7734 call to erlang:system_flag(multi_scheduling, BlockState) has
7735 been made. For information about the return values, see er‐
7736 lang:system_info(multi_scheduling).
7737 Note:
7739 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7740 mally not needed. If you feel that you need to use these fea‐
7741 tures, consider it a few more times again. Blocking multi-sched‐
7742 uling is only to be used as a last resort, as it is most likely
7743 a very inefficient way to solve the problem.
7744 See also erlang:system_info(multi_scheduling), erlang:sys‐
7747 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7748 tem_info(multi_scheduling_blockers), and erlang:sys‐
7749 tem_info(schedulers).
7750 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7752 OldBindType
7753 Types:
7755 How = scheduler_bind_type() | default_bind
7757 OldBindType = scheduler_bind_type()
7758 scheduler_bind_type() =
7759 no_node_processor_spread | no_node_thread_spread | no_spread |
7760 processor_spread | spread | thread_spread |
7761 thread_no_node_processor_spread | unbound
7762 Warning:
7764 This argument is deprecated. Instead of using this argument, use
7765 command-line argument +sbt in erl(1). When this argument is re‐
7766 moved, a final scheduler bind type to use is determined at emu‐
7767 lator boot time.
7768 Controls if and how schedulers are bound to logical processors.
7771 When erlang:system_flag(scheduler_bind_type, How) is called, an
7773 asynchronous signal is sent to all schedulers online, causing
7774 them to try to bind or unbind as requested.
7775 Note:
7777 If a scheduler fails to bind, this is often silently ignored, as
7778 it is not always possible to verify valid logical processor
7779 identifiers. If an error is reported, an error event is logged.
7780 To verify that the schedulers have bound as requested, call er‐
7781 lang:system_info(scheduler_bindings).
7782 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7785 Windows systems, but more systems will be supported in future
7786 releases.
7787 In order for the runtime system to be able to bind schedulers,
7789 the CPU topology must be known. If the runtime system fails to
7790 detect the CPU topology automatically, it can be defined. For
7791 more information on how to define the CPU topology, see command-
7792 line flag +sct in erl(1).
7793 The runtime system does by default not bind schedulers to logi‐
7795 cal processors.
7796 Note:
7798 If the Erlang runtime system is the only OS process binding
7799 threads to logical processors, this improves the performance of
7800 the runtime system. However, if other OS processes (for example,
7801 another Erlang runtime system) also bind threads to logical pro‐
7802 cessors, there can be a performance penalty instead. Sometimes
7803 this performance penalty can be severe. If so, it is recommended
7804 to not bind the schedulers.
7805 Schedulers can be bound in different ways. Argument How deter‐
7808 mines how schedulers are bound and can be any of the following:
7809 unbound:
7811 Same as command-line argument +sbt u in erl(1).
7812 no_spread:
7814 Same as command-line argument +sbt ns in erl(1).
7815 thread_spread:
7817 Same as command-line argument +sbt ts in erl(1).
7818 processor_spread:
7820 Same as command-line argument +sbt ps in erl(1).
7821 spread:
7823 Same as command-line argument +sbt s in erl(1).
7824 no_node_thread_spread:
7826 Same as command-line argument +sbt nnts in erl(1).
7827 no_node_processor_spread:
7829 Same as command-line argument +sbt nnps in erl(1).
7830 thread_no_node_processor_spread:
7832 Same as command-line argument +sbt tnnps in erl(1).
7833 default_bind:
7835 Same as command-line argument +sbt db in erl(1).
7836 The returned value equals How before flag scheduler_bind_type
7838 was changed.
7839 Failures:
7841 notsup:
7843 If binding of schedulers is not supported.
7844 badarg:
7846 If How is not one of the documented alternatives.
7847 badarg:
7849 If CPU topology information is unavailable.
7850 The scheduler bind type can also be set by passing command-line
7852 argument +sbt to erl(1).
7853 For more information, see erlang:system_info(sched‐
7855 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7856 as command-line flags +sbt and +sct in erl(1).
7857 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7859 OldBoolean
7860 Types:
7862 Boolean = OldBoolean = boolean()
7864 Turns on or off scheduler wall time measurements.
7866 For more information, see statistics(scheduler_wall_time).
7868 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7870 OldSchedulersOnline
7871 Types:
7873 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7875 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7877 sOnline <= erlang:system_info(schedulers).
7878 Returns the old value of the flag.
7880 If the emulator was built with support for dirty schedulers,
7882 changing the number of schedulers online can also change the
7883 number of dirty CPU schedulers online. For example, if 12 sched‐
7884 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7885 is used to set the number of schedulers online to 6, then the
7886 number of dirty CPU schedulers online is automatically decreased
7887 by half as well, down to 3. Similarly, the number of dirty CPU
7888 schedulers online increases proportionally to increases in the
7889 number of schedulers online.
7890 For more information, see erlang:system_info(schedulers) and er‐
7892 lang:system_info(schedulers_online).
7893 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
7895 Types:
7897 Logger = PrevLogger = logger | undefined | pid()
7899 Sets the process that will receive the logging messages gener‐
7901 ated by ERTS. If set to undefined, all logging messages gener‐
7902 ated by ERTS will be dropped. The messages will be in the for‐
7903 mat:
7904 {log,Level,Format,ArgList,Metadata} where
7906 Level = atom(),
7908 Format = string(),
7909 ArgList = list(term()),
7910 Metadata = #{ pid => pid(),
7911 group_leader => pid(),
7912 time := logger:timestamp(),
7913 error_logger := #{ emulator := true, tag := atom() }
7914 If the system_logger process dies, this flag will be reset to
7917 logger.
7918 The default is the process named logger.
7920 Returns the old value of the flag.
7922 Note:
7924 This function is designed to be used by the KERNEL logger. Be
7925 careful if you change it to something else as log messages may
7926 be lost. If you want to intercept emulator log messages, do it
7927 by adding a specialized handler to the KERNEL logger.
7928 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7931 Types:
7933 TCW = OldTCW = integer() >= 0
7935 Sets the value of the node trace control word to TCW, which is
7937 to be an unsigned integer. For more information, see function
7938 set_tcw in section "Match Specifications in Erlang" in the
7939 User's Guide.
7940 Returns the old value of the flag.
7942 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7944 OldState
7945 Types:
7947 OldState = preliminary | final | volatile
7949 Finalizes the time offset when single time warp mode is used. If
7951 another time warp mode is used, the time offset state is left
7952 unchanged.
7953 Returns the old state identifier, that is:
7955 * If preliminary is returned, finalization was performed and
7957 the time offset is now final.
7958 * If final is returned, the time offset was already in the fi‐
7960 nal state. This either because another erlang:sys‐
7961 tem_flag(time_offset, finalize) call or because no time warp
7962 mode is used.
7963 * If volatile is returned, the time offset cannot be finalized
7965 because multi-time warp mode is used.
7966 erlang:system_info(Item :: overview) -> boolean()
7968 Returns information about the current system. The documentation
7970 of this function is broken into the following sections in order
7971 to make it easier to navigate.
7972 Memory Allocation:
7974 allocated_areas, allocator, alloc_util_allocators, alloca‐
7975 tor_sizes, elib_malloc
7976 CPU Topology:
7978 cpu_topology, logical_processors, update_cpu_info
7979 Process Information:
7981 fullsweep_after, garbage_collection, heap_sizes, heap_type,
7982 max_heap_size, message_queue_data, min_heap_size,
7983 min_bin_vheap_size, procs
7984 System Limits:
7986 atom_count, atom_limit, ets_count, ets_limit, port_count,
7987 port_limit, process_count, process_limit
7988 System Time:
7990 end_time, os_monotonic_time_source, os_system_time_source,
7991 start_time, time_correction, time_offset, time_warp_mode,
7992 tolerant_timeofday
7993 Scheduler Information:
7995 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
7996 dirty_io_schedulers, multi_scheduling, multi_schedul‐
7997 ing_blockers, normal_multi_scheduling_blockers, sched‐
7998 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
7999 ulers, smp_support, threads, thread_pool_size
8000 Distribution Information:
8002 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
8003 dist_ctrl
8004 System Information:
8006 build_type, c_compiler_used, check_io, compat_rel, de‐
8007 bug_compiled, driver_version, dynamic_trace, dy‐
8008 namic_trace_probes, info, kernel_poll, loaded, machine, mod‐
8009 ified_timing_level, nif_version, otp_release, port_parallel‐
8010 ism, system_architecture, system_logger, system_version,
8011 trace_control_word, version, wordsize
8012 erlang:system_info(Item :: allocated_areas) -> [tuple()]
8014 erlang:system_info(Item :: allocator) ->
8016 {Allocator, Version, Features, Settings}
8017 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
8019 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
8021 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
8023 erlang:system_info(Item :: elib_malloc) -> false
8025 Types:
8027 Allocator = undefined | glibc
8029 Version = [integer() >= 0]
8030 Features = [atom()]
8031 Settings =
8032 [{Subsystem :: atom(),
8033 [{Parameter :: atom(), Value :: term()}]}]
8034 Alloc = atom()
8035 Returns various information about the memory allocators of the
8037 current system (emulator) as specified by Item:
8038 allocated_areas:
8040 Returns a list of tuples with information about miscella‐
8041 neous allocated memory areas.
8042 Each tuple contains an atom describing the type of memory as
8044 first element and the amount of allocated memory in bytes as
8045 second element. When information about allocated and used
8046 memory is present, also a third element is present, contain‐
8047 ing the amount of used memory in bytes.
8048 erlang:system_info(allocated_areas) is intended for debug‐
8050 ging, and the content is highly implementation-dependent.
8051 The content of the results therefore changes when needed
8052 without prior notice.
8053 Notice that the sum of these values is not the total amount
8055 of memory allocated by the emulator. Some values are part of
8056 other values, and some memory areas are not part of the re‐
8057 sult. For information about the total amount of memory allo‐
8058 cated by the emulator, see erlang:memory/0,1.
8059 allocator:
8061 Returns {Allocator, Version, Features, Settings, where:
8062 * Allocator corresponds to the malloc() implementation used.
8064 If Allocator equals undefined, the malloc() implementation
8065 used cannot be identified. glibc can be identified.
8066 * Version is a list of integers (but not a string) repre‐
8068 senting the version of the malloc() implementation used.
8069 * Features is a list of atoms representing the allocation
8071 features used.
8072 * Settings is a list of subsystems, their configurable pa‐
8074 rameters, and used values. Settings can differ between
8075 different combinations of platforms, allocators, and allo‐
8076 cation features. Memory sizes are given in bytes.
8077 See also "System Flags Effecting erts_alloc" in erts_al‐
8079 loc(3).
8080 {allocator, Alloc}:
8082 Returns information about the specified allocator. As from
8083 ERTS 5.6.1, the return value is a list of {instance, Instan‐
8084 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
8085 formation about a specific instance of the allocator. If Al‐
8086 loc is not a recognized allocator, undefined is returned. If
8087 Alloc is disabled, false is returned.
8088 Notice that the information returned is highly implementa‐
8090 tion-dependent and can be changed or removed at any time
8091 without prior notice. It was initially intended as a tool
8092 when developing new allocators, but as it can be of interest
8093 for others it has been briefly documented.
8094 The recognized allocators are listed in erts_alloc(3). In‐
8096 formation about super carriers can be obtained from ERTS 8.0
8097 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
8098 turned list when calling with {allocator, mseg_alloc} also
8099 includes an {erts_mmap, _} tuple as one element in the list.
8100 After reading the erts_alloc(3) documentation, the returned
8102 information more or less speaks for itself, but it can be
8103 worth explaining some things. Call counts are presented by
8104 two values, the first value is giga calls, and the second
8105 value is calls. mbcs and sbcs denote multi-block carriers,
8106 and single-block carriers, respectively. Sizes are presented
8107 in bytes. When a size is not presented, it is the amount of
8108 something. Sizes and amounts are often presented by three
8109 values:
8110 * The first is the current value.
8112 * The second is the maximum value since the last call to er‐
8114 lang:system_info({allocator, Alloc}).
8115 * The third is the maximum value since the emulator was
8117 started.
8118 If only one value is present, it is the current value.
8120 fix_alloc memory block types are presented by two values.
8121 The first value is the memory pool size and the second value
8122 is the used memory size.
8123 alloc_util_allocators:
8125 Returns a list of the names of all allocators using the ERTS
8126 internal alloc_util framework as atoms. For more informa‐
8127 tion, see section The alloc_util framework in erts_alloc(3).
8128 {allocator_sizes, Alloc}:
8130 Returns various size information for the specified alloca‐
8131 tor. The information returned is a subset of the information
8132 returned by erlang:system_info({allocator, Alloc}).
8133 elib_malloc:
8135 This option will be removed in a future release. The return
8136 value will always be false, as the elib_malloc allocator has
8137 been removed.
8138 erlang:system_info(Item :: cpu_topology) -> CpuTopology
8140 erlang:system_info(Item ::
8142 {cpu_topology, defined | detected | used}) ->
8143 CpuTopology
8144 erlang:system_info(Item ::
8146 logical_processors |
8147 logical_processors_available |
8148 logical_processors_online) ->
8149 unknown | integer() >= 1
8150 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
8152 Types:
8154 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8156 All LevelEntrys of a list must contain the same LevelTag,
8157 except on the top level where both node and processor‐
8158 LevelTags can coexist.
8159 level_entry() =
8160 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8161 {LevelTag :: level_tag(),
8162 InfoList :: info_list(),
8163 SubLevel :: sub_level()}
8164 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
8165 level_tag() = core | node | processor | thread
8166 More LevelTags can be introduced in a future release.
8167 sub_level() =
8168 [LevelEntry :: level_entry()] |
8169 (LogicalCpuId :: {logical, integer() >= 0})
8170 info_list() = []
8171 The info_list() can be extended in a future release.
8172 Returns various information about the CPU topology of the cur‐
8174 rent system (emulator) as specified by Item:
8175 cpu_topology:
8177 Returns the CpuTopology currently used by the emulator. The
8178 CPU topology is used when binding schedulers to logical pro‐
8179 cessors. The CPU topology used is the user-defined CPU
8180 topology, if such exists, otherwise the automatically de‐
8181 tected CPU topology, if such exists. If no CPU topology ex‐
8182 ists, undefined is returned.
8183 node refers to Non-Uniform Memory Access (NUMA) nodes.
8185 thread refers to hardware threads (for example, Intel hyper-
8186 threads).
8187 A level in term CpuTopology can be omitted if only one entry
8189 exists and InfoList is empty.
8190 thread can only be a sublevel to core. core can be a sub‐
8192 level to processor or node. processor can be on the top
8193 level or a sublevel to node. node can be on the top level or
8194 a sublevel to processor. That is, NUMA nodes can be proces‐
8195 sor internal or processor external. A CPU topology can con‐
8196 sist of a mix of processor internal and external NUMA nodes,
8197 as long as each logical CPU belongs to one NUMA node. Cache
8198 hierarchy is not part of the CpuTopology type, but will be
8199 in a future release. Other things can also make it into the
8200 CPU topology in a future release. So, expect the CpuTopology
8201 type to change.
8202 {cpu_topology, defined}:
8204 Returns the user-defined CpuTopology. For more information,
8207 see command-line flag +sct in erl(1) and argument cpu_topol‐
8208 ogy.
8209 {cpu_topology, detected}:
8211 Returns the automatically detected CpuTopologyy. The emula‐
8214 tor detects the CPU topology on some newer Linux, Solaris,
8215 FreeBSD, and Windows systems. On Windows system with more
8216 than 32 logical processors, the CPU topology is not de‐
8217 tected.
8218 For more information, see argument cpu_topology.
8220 {cpu_topology, used}:
8222 Returns CpuTopology used by the emulator. For more informa‐
8223 tion, see argument cpu_topology.
8224 logical_processors:
8226 Returns the detected number of logical processors configured
8227 in the system. The return value is either an integer, or the
8228 atom unknown if the emulator cannot detect the configured
8229 logical processors.
8230 logical_processors_available:
8232 Returns the detected number of logical processors available
8233 to the Erlang runtime system. The return value is either an
8234 integer, or the atom unknown if the emulator cannot detect
8235 the available logical processors. The number of available
8236 logical processors is less than or equal to the number of
8237 logical processors online.
8238 logical_processors_online:
8240 Returns the detected number of logical processors online on
8241 the system. The return value is either an integer, or the
8242 atom unknown if the emulator cannot detect logical proces‐
8243 sors online. The number of logical processors online is less
8244 than or equal to the number of logical processors config‐
8245 ured.
8246 cpu_quota:
8248 Returns the detected CPU quota the emulator is limited by.
8249 The return value is an integer saying how many processors'
8250 worth of runtime we get (between 1 and the number of logical
8251 processors), or the atom unknown if the emulator cannot de‐
8252 tect a quota.
8253 update_cpu_info:
8255 The runtime system rereads the CPU information available and
8256 updates its internally stored information about the detected
8257 CPU topology and the number of logical processors config‐
8258 ured, online, available, and cpu quota.
8259 If the CPU information has changed since the last time it
8261 was read, the atom changed is returned, otherwise the atom
8262 unchanged. If the CPU information has changed, you probably
8263 want to adjust the number of schedulers online. You typi‐
8264 cally want to have as many schedulers online as logical pro‐
8265 cessors available.
8266 erlang:system_info(Item :: fullsweep_after) ->
8268 {fullsweep_after, integer() >= 0}
8269 erlang:system_info(Item :: garbage_collection) ->
8271 [{atom(), integer()}]
8272 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
8274 erlang:system_info(Item :: heap_type) -> private
8276 erlang:system_info(Item :: max_heap_size) ->
8278 {max_heap_size,
8279 MaxHeapSize :: max_heap_size()}
8280 erlang:system_info(Item :: message_queue_data) ->
8282 message_queue_data()
8283 erlang:system_info(Item :: min_heap_size) ->
8285 {min_heap_size,
8286 MinHeapSize :: integer() >= 1}
8287 erlang:system_info(Item :: min_bin_vheap_size) ->
8289 {min_bin_vheap_size,
8290 MinBinVHeapSize :: integer() >= 1}
8291 erlang:system_info(Item :: procs) -> binary()
8293 Types:
8295 message_queue_data() = off_heap | on_heap
8297 max_heap_size() =
8298 integer() >= 0 |
8299 #{size => integer() >= 0,
8300 kill => boolean(),
8301 error_logger => boolean()}
8302 Returns information about the default process heap settings:
8304 fullsweep_after:
8306 Returns {fullsweep_after, integer() >= 0}, which is the
8307 fullsweep_after garbage collection setting used by default.
8308 For more information, see garbage_collection described be‐
8309 low.
8310 garbage_collection:
8312 Returns a list describing the default garbage collection
8313 settings. A process spawned on the local node by a spawn or
8314 spawn_link uses these garbage collection settings. The de‐
8315 fault settings can be changed by using erlang:system_flag/2.
8316 spawn_opt/2,3,4 can spawn a process that does not use the
8317 default settings.
8318 heap_sizes:
8320 Returns a list of integers representing valid heap sizes in
8321 words. All Erlang heaps are sized from sizes in this list.
8322 heap_type:
8324 Returns the heap type used by the current emulator. One heap
8325 type exists:
8326 private:
8328 Each process has a heap reserved for its use and no ref‐
8329 erences between heaps of different processes are allowed.
8330 Messages passed between processes are copied between
8331 heaps.
8332 max_heap_size:
8334 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
8335 the current system-wide maximum heap size settings for
8336 spawned processes. This setting can be set using the com‐
8337 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
8338 also be changed at runtime using erlang:sys‐
8339 tem_flag(max_heap_size, MaxHeapSize). For more details about
8340 the max_heap_size process flag, see
8341 process_flag(max_heap_size, MaxHeapSize).
8342 message_queue_data:
8344 Returns the default value of the message_queue_data process
8345 flag, which can be either off_heap or on_heap. The default
8346 value is set by the command-line argument +hmqd in erl(1).
8347 For more information, see the documentation of
8348 process_flag(message_queue_data, MQD).
8349 min_heap_size:
8351 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
8352 the current system-wide minimum heap size for spawned pro‐
8353 cesses.
8354 min_bin_vheap_size:
8356 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
8357 VHeapSize is the current system-wide minimum binary virtual
8358 heap size for spawned processes.
8359 procs:
8361 Returns a binary containing a string of process and port in‐
8362 formation formatted as in Erlang crash dumps. For more in‐
8363 formation, see section How to interpret the Erlang crash
8364 dumps in the User's Guide.
8365 erlang:system_info(Item :: atom_count) -> integer() >= 1
8367 erlang:system_info(Item :: atom_limit) -> integer() >= 1
8369 erlang:system_info(Item :: ets_count) -> integer() >= 1
8371 erlang:system_info(Item :: ets_limit) -> integer() >= 1
8373 erlang:system_info(Item :: port_count) -> integer() >= 0
8375 erlang:system_info(Item :: port_limit) -> integer() >= 1
8377 erlang:system_info(Item :: process_count) -> integer() >= 1
8379 erlang:system_info(Item :: process_limit) -> integer() >= 1
8381 Returns information about the current system (emulator) limits
8383 as specified by Item:
8384 atom_count:
8386 Returns the number of atoms currently existing at the local
8387 node. The value is given as an integer.
8388 atom_limit:
8390 Returns the maximum number of atoms allowed. This limit can
8391 be increased at startup by passing command-line flag +t to
8392 erl(1).
8393 ets_count:
8395 Returns the number of ETS tables currently existing at the
8396 local node.
8397 ets_limit:
8399 Returns the limit for number of ETS tables. This limit is
8400 partially obsolete and number of tables are only limited by
8401 available memory.
8402 port_count:
8404 Returns the number of ports currently existing at the local
8405 node. The value is given as an integer. This is the same
8406 value as returned by length(erlang:ports()), but more effi‐
8407 cient.
8408 port_limit:
8410 Returns the maximum number of simultaneously existing ports
8411 at the local node as an integer. This limit can be config‐
8412 ured at startup by using command-line flag +Q in erl(1).
8413 process_count:
8415 Returns the number of processes currently existing at the
8416 local node. The value is given as an integer. This is the
8417 same value as returned by length(processes()), but more ef‐
8418 ficient.
8419 process_limit:
8421 Returns the maximum number of simultaneously existing pro‐
8422 cesses at the local node. The value is given as an integer.
8423 This limit can be configured at startup by using command-
8424 line flag +P in erl(1).
8425 erlang:system_info(Item :: end_time) -> integer() >= 0
8427 erlang:system_info(Item :: os_monotonic_time_source) ->
8429 [{atom(), term()}]
8430 erlang:system_info(Item :: os_system_time_source) ->
8432 [{atom(), term()}]
8433 erlang:system_info(Item :: start_time) -> integer()
8435 erlang:system_info(Item :: time_correction) -> true | false
8437 erlang:system_info(Item :: time_offset) ->
8439 preliminary | final | volatile
8440 erlang:system_info(Item :: time_warp_mode) ->
8442 no_time_warp | single_time_warp |
8443 multi_time_warp
8444 erlang:system_info(Item :: tolerant_timeofday) ->
8446 enabled | disabled
8447 Returns information about the current system (emulator) time as
8449 specified by Item:
8450 end_time:
8452 The last Erlang monotonic time in native time unit that can
8453 be represented internally in the current Erlang runtime sys‐
8454 tem instance. The time between the start time and the end
8455 time is at least a quarter of a millennium.
8456 os_monotonic_time_source:
8458 Returns a list containing information about the source of OS
8459 monotonic time that is used by the runtime system.
8460 If [] is returned, no OS monotonic time is available. The
8462 list contains two-tuples with Keys as first element, and
8463 Values as second element. The order of these tuples is unde‐
8464 fined. The following tuples can be part of the list, but
8465 more tuples can be introduced in the future:
8466 {function, Function}:
8468 Function is the name of the function used. This tuple al‐
8469 ways exists if OS monotonic time is available to the run‐
8470 time system.
8471 {clock_id, ClockId}:
8473 This tuple only exists if Function can be used with dif‐
8474 ferent clocks. ClockId corresponds to the clock identifier
8475 used when calling Function.
8476 {resolution, OsMonotonicTimeResolution}:
8478 Highest possible resolution of current OS monotonic time
8479 source as parts per second. If no resolution information
8480 can be retrieved from the OS, OsMonotonicTimeResolution is
8481 set to the resolution of the time unit of Functions return
8482 value. That is, the actual resolution can be lower than
8483 OsMonotonicTimeResolution. Notice that the resolution does
8484 not say anything about the accuracy or whether the pre‐
8485 cision aligns with the resolution. You do, however, know
8486 that the precision is not better than OsMonotonicTimeReso‐
8487 lution.
8488 {extended, Extended}:
8490 Extended equals yes if the range of time values has been
8491 extended; otherwise Extended equals no. The range must be
8492 extended if Function returns values that wrap fast. This
8493 typically is the case when the return value is a 32-bit
8494 value.
8495 {parallel, Parallel}:
8497 Parallel equals yes if Function is called in parallel from
8498 multiple threads. If it is not called in parallel, because
8499 calls must be serialized, Parallel equals no.
8500 {time, OsMonotonicTime}:
8502 OsMonotonicTime equals current OS monotonic time in native
8503 time unit.
8504 os_system_time_source:
8506 Returns a list containing information about the source of OS
8507 system time that is used by the runtime system.
8508 The list contains two-tuples with Keys as first element, and
8510 Values as second element. The order of these tuples is unde‐
8511 fined. The following tuples can be part of the list, but
8512 more tuples can be introduced in the future:
8513 {function, Function}:
8515 Function is the name of the funcion used.
8516 {clock_id, ClockId}:
8518 Exists only if Function can be used with different clocks.
8519 ClockId corresponds to the clock identifier used when
8520 calling Function.
8521 {resolution, OsSystemTimeResolution}:
8523 Highest possible resolution of current OS system time
8524 source as parts per second. If no resolution information
8525 can be retrieved from the OS, OsSystemTimeResolution is
8526 set to the resolution of the time unit of Functions return
8527 value. That is, the actual resolution can be lower than
8528 OsSystemTimeResolution. Notice that the resolution does
8529 not say anything about the accuracy or whether the pre‐
8530 cision do align with the resolution. You do, however, know
8531 that the precision is not better than OsSystemTimeResolu‐
8532 tion.
8533 {parallel, Parallel}:
8535 Parallel equals yes if Function is called in parallel from
8536 multiple threads. If it is not called in parallel, because
8537 calls needs to be serialized, Parallel equals no.
8538 {time, OsSystemTime}:
8540 OsSystemTime equals current OS system time in native time
8541 unit.
8542 start_time:
8544 The Erlang monotonic time in native time unit at the time
8545 when current Erlang runtime system instance started.
8546 See also erlang:system_info(end_time).
8548 time_correction:
8550 Returns a boolean value indicating whether time correction
8551 is enabled or not.
8552 time_offset:
8554 Returns the state of the time offset:
8555 preliminary:
8557 The time offset is preliminary, and will be changed and
8558 finalized later. The preliminary time offset is used dur‐
8559 ing the preliminary phase of the single time warp mode.
8560 final:
8562 The time offset is final. This either because no time
8563 warp mode is used, or because the time offset have been
8564 finalized when single time warp mode is used.
8565 volatile:
8567 The time offset is volatile. That is, it can change at any
8568 time. This is because multi-time warp mode is used.
8569 time_warp_mode:
8571 Returns a value identifying the time warp mode that is
8572 used:
8573 no_time_warp:
8575 The no time warp mode is used.
8576 single_time_warp:
8578 The single time warp mode is used.
8579 multi_time_warp:
8581 The multi-time warp mode is used.
8582 tolerant_timeofday:
8584 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8585 sation for sudden changes of system time is enabled or dis‐
8586 abled. Such compensation is enabled when the time offset is
8587 final, and time correction is enabled.
8588 erlang:system_info(Item :: dirty_cpu_schedulers) ->
8590 integer() >= 0
8591 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
8593 integer() >= 0
8594 erlang:system_info(Item :: dirty_io_schedulers) ->
8596 integer() >= 0
8597 erlang:system_info(Item :: multi_scheduling) ->
8599 disabled | blocked | blocked_normal |
8600 enabled
8601 erlang:system_info(Item :: multi_scheduling_blockers) ->
8603 [Pid :: pid()]
8604 erlang:system_info(Item :: otp_release) -> string()
8606 erlang:system_info(Item :: scheduler_bind_type) ->
8608 spread | processor_spread | thread_spread |
8609 thread_no_node_processor_spread |
8610 no_node_processor_spread |
8611 no_node_thread_spread | no_spread | unbound
8612 erlang:system_info(Item :: scheduler_bindings) -> tuple()
8614 erlang:system_info(Item :: scheduler_id) ->
8616 SchedulerId :: integer() >= 1
8617 erlang:system_info(Item :: schedulers | schedulers_online) ->
8619 integer() >= 1
8620 erlang:system_info(Item :: smp_support) -> boolean()
8622 erlang:system_info(Item :: threads) -> boolean()
8624 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
8626 Returns information about schedulers, scheduling and threads in
8628 the current system as specified by Item:
8629 dirty_cpu_schedulers:
8631 Returns the number of dirty CPU scheduler threads used by
8632 the emulator. Dirty CPU schedulers execute CPU-bound native
8633 functions, such as NIFs, linked-in driver code, and BIFs
8634 that cannot be managed cleanly by the normal emulator sched‐
8635 ulers.
8636 The number of dirty CPU scheduler threads is determined at
8638 emulator boot time and cannot be changed after that. How‐
8639 ever, the number of dirty CPU scheduler threads online can
8640 be changed at any time. The number of dirty CPU schedulers
8641 can be set at startup by passing command-line flag +SDcpu or
8642 +SDPcpu in erl(1).
8643 See also erlang:system_flag(dirty_cpu_schedulers_online,
8645 DirtyCPUSchedulersOnline), erlang:sys‐
8646 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
8647 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8648 ulers), erlang:system_info(schedulers_online), and er‐
8649 lang:system_flag(schedulers_online, SchedulersOnline).
8650 dirty_cpu_schedulers_online:
8652 Returns the number of dirty CPU schedulers online. The re‐
8653 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
8654 where N is the smallest of the return values of erlang:sys‐
8655 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
8656 ulers_online).
8657 The number of dirty CPU schedulers online can be set at
8659 startup by passing command-line flag +SDcpu in erl(1).
8660 For more information, see erlang:sys‐
8662 tem_info(dirty_cpu_schedulers), erlang:sys‐
8663 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8664 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
8665 ulers_online, DirtyCPUSchedulersOnline).
8666 dirty_io_schedulers:
8668 Returns the number of dirty I/O schedulers as an integer.
8669 Dirty I/O schedulers execute I/O-bound native functions,
8670 such as NIFs and linked-in driver code, which cannot be man‐
8671 aged cleanly by the normal emulator schedulers.
8672 This value can be set at startup by passing command-line ar‐
8674 gument +SDio in erl(1).
8675 For more information, see erlang:sys‐
8677 tem_info(dirty_cpu_schedulers), erlang:sys‐
8678 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
8679 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
8680 line).
8681 multi_scheduling:
8683 Returns one of the following:
8684 disabled:
8686 The emulator has been started with only one scheduler
8687 thread.
8688 blocked:
8690 The emulator has more than one scheduler thread, but all
8691 scheduler threads except one are blocked. That is, only
8692 one scheduler thread schedules Erlang processes and exe‐
8693 cutes Erlang code.
8694 blocked_normal:
8696 The emulator has more than one scheduler thread, but all
8697 normal scheduler threads except one are blocked. Notice
8698 that dirty schedulers are not blocked, and can schedule
8699 Erlang processes and execute native code.
8700 enabled:
8702 The emulator has more than one scheduler thread, and no
8703 scheduler threads are blocked. That is, all available
8704 scheduler threads schedule Erlang processes and execute
8705 Erlang code.
8706 See also erlang:system_flag(multi_scheduling, BlockState),
8708 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8709 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8710 tem_info(schedulers).
8711 multi_scheduling_blockers:
8713 Returns a list of Pids when multi-scheduling is blocked,
8714 otherwise the empty list is returned. The Pids in the list
8715 represent all the processes currently blocking multi-sched‐
8716 uling. A Pid occurs only once in the list, even if the cor‐
8717 responding process has blocked multiple times.
8718 See also erlang:system_flag(multi_scheduling, BlockState),
8720 erlang:system_info(multi_scheduling), erlang:sys‐
8721 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8722 tem_info(schedulers).
8723 normal_multi_scheduling_blockers:
8725 Returns a list of Pids when normal multi-scheduling is
8726 blocked (that is, all normal schedulers but one is blocked),
8727 otherwise the empty list is returned. The Pids in the list
8728 represent all the processes currently blocking normal multi-
8729 scheduling. A Pid occurs only once in the list, even if the
8730 corresponding process has blocked multiple times.
8731 See also erlang:system_flag(multi_scheduling, BlockState),
8733 erlang:system_info(multi_scheduling), erlang:sys‐
8734 tem_info(multi_scheduling_blockers), and erlang:sys‐
8735 tem_info(schedulers).
8736 scheduler_bind_type:
8738 Returns information about how the user has requested sched‐
8739 ulers to be bound or not bound.
8740 Notice that although a user has requested schedulers to be
8742 bound, they can silently have failed to bind. To inspect the
8743 scheduler bindings, call erlang:system_info(scheduler_bind‐
8744 ings).
8745 For more information, see command-line argument +sbt in
8747 erl(1) and erlang:system_info(scheduler_bindings).
8748 scheduler_bindings:
8750 Returns information about the currently used scheduler bind‐
8751 ings.
8752 A tuple of a size equal to erlang:system_info(schedulers) is
8754 returned. The tuple elements are integers or the atom un‐
8755 bound. Logical processor identifiers are represented as in‐
8756 tegers. The Nth element of the tuple equals the current
8757 binding for the scheduler with the scheduler identifier
8758 equal to N. For example, if the schedulers are bound, ele‐
8759 ment(erlang:system_info(scheduler_id), erlang:sys‐
8760 tem_info(scheduler_bindings)) returns the identifier of the
8761 logical processor that the calling process is executing on.
8762 Notice that only schedulers online can be bound to logical
8764 processors.
8765 For more information, see command-line argument +sbt in
8767 erl(1) and erlang:system_info(schedulers_online).
8768 scheduler_id:
8770 Returns the scheduler ID (SchedulerId) of the scheduler
8771 thread that the calling process is executing on. SchedulerId
8772 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8773 tem_info(schedulers).
8774 See also erlang:system_info(schedulers).
8776 schedulers:
8778 Returns the number of scheduler threads used by the emula‐
8779 tor. Scheduler threads online schedules Erlang processes and
8780 Erlang ports, and execute Erlang code and Erlang linked-in
8781 driver code.
8782 The number of scheduler threads is determined at emulator
8784 boot time and cannot be changed later. However, the number
8785 of schedulers online can be changed at any time.
8786 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8788 line), erlang:system_info(schedulers_online), erlang:sys‐
8789 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8790 BlockState), erlang:system_info(multi_scheduling), er‐
8791 lang:system_info(normal_multi_scheduling_blockers) and er‐
8792 lang:system_info(multi_scheduling_blockers).
8793 schedulers_online:
8795 Returns the number of schedulers online. The scheduler iden‐
8796 tifiers of schedulers online satisfy the relationship 1 <=
8797 SchedulerId <= erlang:system_info(schedulers_online).
8798 For more information, see erlang:system_info(schedulers) and
8800 erlang:system_flag(schedulers_online, SchedulersOnline).
8801 smp_support:
8803 Returns true.
8804 threads:
8806 Returns true.
8807 thread_pool_size:
8809 Returns the number of async threads in the async thread pool
8812 used for asynchronous driver calls
8813 (erl_driver:driver_async()). The value is given as an inte‐
8814 ger.
8815 erlang:system_info(Item :: creation) -> integer()
8817 erlang:system_info(Item :: delayed_node_table_gc) ->
8819 infinity | integer() >= 0
8820 erlang:system_info(Item :: dist) -> binary()
8822 erlang:system_info(Item :: dist_buf_busy_limit) ->
8824 integer() >= 0
8825 erlang:system_info(Item :: dist_ctrl) ->
8827 {Node :: node(),
8828 ControllingEntity :: port() | pid()}
8829 Returns information about Erlang Distribution in the current
8831 system as specified by Item:
8832 creation:
8834 Returns the creation of the local node as an integer. The
8835 creation is changed when a node is restarted. The creation
8836 of a node is stored in process identifiers, port identi‐
8837 fiers, and references. This makes it (to some extent) possi‐
8838 ble to distinguish between identifiers from different incar‐
8839 nations of a node. The valid creations are integers in the
8840 range 1..3, but this will probably change in a future re‐
8841 lease. If the node is not alive, 0 is returned.
8842 delayed_node_table_gc:
8844 Returns the amount of time in seconds garbage collection of
8845 an entry in a node table is delayed. This limit can be set
8846 on startup by passing command-line flag +zdntgc to erl(1).
8847 For more information, see the documentation of the command-
8848 line flag.
8849 dist:
8851 Returns a binary containing a string of distribution infor‐
8852 mation formatted as in Erlang crash dumps. For more informa‐
8853 tion, see section How to interpret the Erlang crash dumps
8854 in the User's Guide.
8855 dist_buf_busy_limit:
8857 Returns the value of the distribution buffer busy limit in
8858 bytes. This limit can be set at startup by passing command-
8859 line flag +zdbbl to erl(1).
8860 dist_ctrl:
8862 Returns a list of tuples {Node, ControllingEntity}, one en‐
8863 try for each connected remote node. Node is the node name
8864 and ControllingEntity is the port or process identifier re‐
8865 sponsible for the communication to that node. More specifi‐
8866 cally, ControllingEntity for nodes connected through TCP/IP
8867 (the normal case) is the socket used in communication with
8868 the specific node.
8869 erlang:system_info(Item :: build_type) ->
8871 opt | debug | purify | quantify | purecov |
8872 gcov | valgrind | gprof | lcnt | frmptr
8873 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
8875 erlang:system_info(Item :: check_io) -> [term()]
8877 erlang:system_info(Item :: compat_rel) -> integer()
8879 erlang:system_info(Item :: debug_compiled) -> boolean()
8881 erlang:system_info(Item :: driver_version) -> string()
8883 erlang:system_info(Item :: dynamic_trace) ->
8885 none | dtrace | systemtap
8886 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
8888 erlang:system_info(Item :: info) -> binary()
8890 erlang:system_info(Item :: kernel_poll) -> boolean()
8892 erlang:system_info(Item :: loaded) -> binary()
8894 erlang:system_info(Item :: machine) -> string()
8896 erlang:system_info(Item :: modified_timing_level) ->
8898 integer() | undefined
8899 erlang:system_info(Item :: nif_version) -> string()
8901 erlang:system_info(Item :: otp_release) -> string()
8903 erlang:system_info(Item :: port_parallelism) -> boolean()
8905 erlang:system_info(Item :: system_architecture) -> string()
8907 erlang:system_info(Item :: system_logger) ->
8909 logger | undefined | pid()
8910 erlang:system_info(Item :: system_version) -> string()
8912 erlang:system_info(Item :: trace_control_word) ->
8914 integer() >= 0
8915 erlang:system_info(Item :: version) -> string()
8917 erlang:system_info(Item ::
8919 wordsize |
8920 {wordsize, internal} |
8921 {wordsize, external}) ->
8922 4 | 8
8923 Returns various information about the current system (emulator)
8925 as specified by Item:
8926 build_type:
8928 Returns an atom describing the build type of the runtime
8929 system. This is normally the atom opt for optimized. Other
8930 possible return values are debug, purify, quantify, purecov,
8931 gcov, valgrind, gprof, and lcnt. Possible return values can
8932 be added or removed at any time without prior notice.
8933 c_compiler_used:
8935 Returns a two-tuple describing the C compiler used when com‐
8936 piling the runtime system. The first element is an atom de‐
8937 scribing the name of the compiler, or undefined if unknown.
8938 The second element is a term describing the version of the
8939 compiler, or undefined if unknown.
8940 check_io:
8942 Returns a list containing miscellaneous information about
8943 the emulators internal I/O checking. Notice that the content
8944 of the returned list can vary between platforms and over
8945 time. It is only guaranteed that a list is returned.
8946 compat_rel:
8948 Returns the compatibility mode of the local node as an inte‐
8949 ger. The integer returned represents the Erlang/OTP release
8950 that the current emulator has been set to be backward com‐
8951 patible with. The compatibility mode can be configured at
8952 startup by using command-line flag +R in erl(1).
8953 debug_compiled:
8955 Returns true if the emulator has been debug-compiled, other‐
8956 wise false.
8957 driver_version:
8959 Returns a string containing the Erlang driver version used
8960 by the runtime system. It has the form "<major ver>.<minor
8961 ver>".
8962 dynamic_trace:
8964 Returns an atom describing the dynamic trace framework com‐
8965 piled into the virtual machine. It can be dtrace, systemtap,
8966 or none. For a commercial or standard build, it is always
8967 none. The other return values indicate a custom configura‐
8968 tion (for example, ./configure --with-dynamic-trace=dtrace).
8969 For more information about dynamic tracing, see dyntrace(3)
8970 manual page and the README.dtrace/README.systemtap files in
8971 the Erlang source code top directory.
8972 dynamic_trace_probes:
8974 Returns a boolean() indicating if dynamic trace probes
8975 (dtrace or systemtap) are built into the emulator. This can
8976 only be true if the virtual machine was built for dynamic
8977 tracing (that is, system_info(dynamic_trace) returns dtrace
8978 or systemtap).
8979 info:
8981 Returns a binary containing a string of miscellaneous system
8982 information formatted as in Erlang crash dumps. For more in‐
8983 formation, see section How to interpret the Erlang crash
8984 dumps in the User's Guide.
8985 kernel_poll:
8987 Returns true if the emulator uses some kind of kernel-poll
8988 implementation, otherwise false.
8989 loaded:
8991 Returns a binary containing a string of loaded module infor‐
8992 mation formatted as in Erlang crash dumps. For more informa‐
8993 tion, see section How to interpret the Erlang crash dumps in
8994 the User's Guide.
8995 machine:
8997 Returns a string containing the Erlang machine name.
8998 modified_timing_level:
9000 Returns the modified timing-level (an integer) if modified
9001 timing is enabled, otherwise undefined. For more information
9002 about modified timing, see command-line flag +T in erl(1)
9003 nif_version:
9005 Returns a string containing the version of the Erlang NIF
9006 interface used by the runtime system. It is on the form
9007 "<major ver>.<minor ver>".
9008 otp_release:
9010 Returns a string containing the OTP release number of the
9013 OTP release that the currently executing ERTS application is
9014 part of.
9015 As from Erlang/OTP 17, the OTP release number corresponds to
9017 the major OTP version number. No erlang:system_info() argu‐
9018 ment gives the exact OTP version. This is because the exact
9019 OTP version in the general case is difficult to determine.
9020 For more information, see the description of versions in
9021 System principles in System Documentation.
9022 port_parallelism:
9024 Returns the default port parallelism scheduling hint used.
9025 For more information, see command-line argument +spp in
9026 erl(1).
9027 system_architecture:
9029 Returns a string containing the processor and OS architec‐
9030 ture the emulator is built for.
9031 system_logger:
9033 Returns the current system_logger as set by erlang:sys‐
9034 tem_flag(system_logger, _).
9035 system_version:
9037 Returns a string containing version number and some impor‐
9038 tant properties, such as the number of schedulers.
9039 trace_control_word:
9041 Returns the value of the node trace control word. For more
9042 information, see function get_tcw in section Match Specifi‐
9043 cations in Erlang in the User's Guide.
9044 version:
9046 Returns a string containing the version number of the emula‐
9047 tor.
9048 wordsize:
9050 Same as {wordsize, internal}.
9051 {wordsize, internal}:
9053 Returns the size of Erlang term words in bytes as an inte‐
9054 ger, that is, 4 is returned on a 32-bit architecture, and 8
9055 is returned on a pure 64-bit architecture. On a halfword
9056 64-bit emulator, 4 is returned, as the Erlang terms are
9057 stored using a virtual word size of half the system word
9058 size.
9059 {wordsize, external}:
9061 Returns the true word size of the emulator, that is, the
9062 size of a pointer. The value is given in bytes as an inte‐
9063 ger. On a pure 32-bit architecture, 4 is returned. On both a
9064 half word and on a pure 64-bit architecture, 8 is returned.
9065 erlang:system_monitor() -> MonSettings
9067 Types:
9069 MonSettings = undefined | {MonitorPid, Options}
9071 MonitorPid = pid()
9072 Options = [system_monitor_option()]
9073 system_monitor_option() =
9074 busy_port | busy_dist_port |
9075 {long_gc, integer() >= 0} |
9076 {long_schedule, integer() >= 0} |
9077 {large_heap, integer() >= 0}
9078 Returns the current system monitoring settings set by er‐
9080 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
9081 no settings exist. The order of the options can be different
9082 from the one that was set.
9083 erlang:system_monitor(Arg) -> MonSettings
9085 Types:
9087 Arg = MonSettings = undefined | {MonitorPid, Options}
9089 MonitorPid = pid()
9090 Options = [system_monitor_option()]
9091 system_monitor_option() =
9092 busy_port | busy_dist_port |
9093 {long_gc, integer() >= 0} |
9094 {long_schedule, integer() >= 0} |
9095 {large_heap, integer() >= 0}
9096 When called with argument undefined, all system performance mon‐
9098 itoring settings are cleared.
9099 Calling the function with {MonitorPid, Options} as argument is
9101 the same as calling erlang:system_monitor(MonitorPid, Options).
9102 Returns the previous system monitor settings just like er‐
9104 lang:system_monitor/0.
9105 erlang:system_monitor(MonitorPid, Options) -> MonSettings
9107 Types:
9109 MonitorPid = pid()
9111 Options = [system_monitor_option()]
9112 MonSettings = undefined | {OldMonitorPid, OldOptions}
9113 OldMonitorPid = pid()
9114 OldOptions = [system_monitor_option()]
9115 system_monitor_option() =
9116 busy_port | busy_dist_port |
9117 {long_gc, integer() >= 0} |
9118 {long_schedule, integer() >= 0} |
9119 {large_heap, integer() >= 0}
9120 Sets the system performance monitoring options. MonitorPid is a
9122 local process identifier (pid) receiving system monitor mes‐
9123 sages. The second argument is a list of monitoring options:
9124 {long_gc, Time}:
9126 If a garbage collection in the system takes at least Time
9127 wall clock milliseconds, a message {monitor, GcPid, long_gc,
9128 Info} is sent to MonitorPid. GcPid is the pid that was
9129 garbage collected. Info is a list of two-element tuples de‐
9130 scribing the result of the garbage collection.
9131 One of the tuples is {timeout, GcTime}, where GcTime is the
9133 time for the garbage collection in milliseconds. The other
9134 tuples are tagged with heap_size, heap_block_size,
9135 stack_size, mbuf_size, old_heap_size, and
9136 old_heap_block_size. These tuples are explained in the de‐
9137 scription of trace message gc_minor_start (see er‐
9138 lang:trace/3). New tuples can be added, and the order of the
9139 tuples in the Info list can be changed at any time without
9140 prior notice.
9141 {long_schedule, Time}:
9143 If a process or port in the system runs uninterrupted for at
9144 least Time wall clock milliseconds, a message {monitor, Pi‐
9145 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
9146 Port is the process or port that was running. Info is a list
9147 of two-element tuples describing the event.
9148 If a pid(), the tuples {timeout, Millis}, {in, Location},
9150 and {out, Location} are present, where Location is either an
9151 MFA ({Module, Function, Arity}) describing the function
9152 where the process was scheduled in/out, or the atom unde‐
9153 fined.
9154 If a port(), the tuples {timeout, Millis} and {port_op,Op}
9156 are present. Op is one of proc_sig, timeout, input, output,
9157 event, or dist_cmd, depending on which driver callback was
9158 executing.
9159 proc_sig is an internal operation and is never to appear,
9161 while the others represent the corresponding driver call‐
9162 backs timeout, ready_input, ready_output, event, and outputv
9163 (when the port is used by distribution). Value Millis in tu‐
9164 ple timeout informs about the uninterrupted execution time
9165 of the process or port, which always is equal to or higher
9166 than the Time value supplied when starting the trace. New
9167 tuples can be added to the Info list in a future release.
9168 The order of the tuples in the list can be changed at any
9169 time without prior notice.
9170 This can be used to detect problems with NIFs or drivers
9172 that take too long to execute. 1 ms is considered a good
9173 maximum time for a driver callback or a NIF. However, a
9174 time-sharing system is usually to consider everything < 100
9175 ms as "possible" and fairly "normal". However, longer sched‐
9176 ule times can indicate swapping or a misbehaving NIF/driver.
9177 Misbehaving NIFs and drivers can cause bad resource utiliza‐
9178 tion and bad overall system performance.
9179 {large_heap, Size}:
9181 If a garbage collection in the system results in the allo‐
9182 cated size of a heap being at least Size words, a message
9183 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
9184 GcPid and Info are the same as for long_gc earlier, except
9185 that the tuple tagged with timeout is not present.
9186 The monitor message is sent if the sum of the sizes of all
9188 memory blocks allocated for all heap generations after a
9189 garbage collection is equal to or higher than Size.
9190 When a process is killed by max_heap_size, it is killed be‐
9192 fore the garbage collection is complete and thus no large
9193 heap message is sent.
9194 busy_port:
9196 If a process in the system gets suspended because it sends
9197 to a busy port, a message {monitor, SusPid, busy_port, Port}
9198 is sent to MonitorPid. SusPid is the pid that got suspended
9199 when sending to Port.
9200 busy_dist_port:
9202 If a process in the system gets suspended because it sends
9203 to a process on a remote node whose inter-node communication
9204 was handled by a busy port, a message {monitor, SusPid,
9205 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
9206 pid that got suspended when sending through the inter-node
9207 communication port Port.
9208 Returns the previous system monitor settings just like er‐
9210 lang:system_monitor/0.
9211 The arguments to system_monitor/2 specifies how all system moni‐
9213 toring on the node should be done, not how it should be changed.
9214 This means only one process at a time (MonitorPid) can be the
9215 receiver of system monitor messages. Also, the way to clear a
9216 specific monitor option is to not include it in the list Op‐
9217 tions. All system monitoring will, however, be cleared if the
9218 process identified by MonitorPid terminates.
9219 There are no special option values (like zero) to clear an op‐
9221 tion. Some of the options have a unspecified minimum value.
9222 Lower values will be adjusted to the minimum value. For example,
9223 it is currently not possible to monitor all garbage collections
9224 with {long_gc, 0}.
9225 Note:
9227 If a monitoring process gets so large that it itself starts to
9228 cause system monitor messages when garbage collecting, the mes‐
9229 sages enlarge the process message queue and probably make the
9230 problem worse.
9231 Keep the monitoring process neat and do not set the system moni‐
9233 tor limits too tight.
9234 Failures:
9237 badarg:
9239 If MonitorPid does not exist.
9240 badarg:
9242 If MonitorPid is not a local process.
9243 erlang:system_profile() -> ProfilerSettings
9245 Types:
9247 ProfilerSettings = undefined | {ProfilerPid, Options}
9249 ProfilerPid = pid() | port()
9250 Options = [system_profile_option()]
9251 system_profile_option() =
9252 exclusive | runnable_ports | runnable_procs | scheduler |
9253 timestamp | monotonic_timestamp | strict_monotonic_timestamp
9254 Returns the current system profiling settings set by erlang:sys‐
9256 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
9257 are no settings. The order of the options can be different from
9258 the one that was set.
9259 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
9261 Types:
9263 ProfilerPid = pid() | port() | undefined
9265 Options = [system_profile_option()]
9266 ProfilerSettings =
9267 undefined | {pid() | port(), [system_profile_option()]}
9268 system_profile_option() =
9269 exclusive | runnable_ports | runnable_procs | scheduler |
9270 timestamp | monotonic_timestamp | strict_monotonic_timestamp
9271 Sets system profiler options. ProfilerPid is a local process
9273 identifier (pid) or port receiving profiling messages. The re‐
9274 ceiver is excluded from all profiling. The second argument is a
9275 list of profiling options:
9276 exclusive:
9278 If a synchronous call to a port from a process is done, the
9279 calling process is considered not runnable during the call
9280 runtime to the port. The calling process is notified as in‐
9281 active, and later active when the port callback returns.
9282 monotonic_timestamp:
9284 Time stamps in profile messages use Erlang monotonic time.
9285 The time stamp (Ts) has the same format and value as pro‐
9286 duced by erlang:monotonic_time(nanosecond).
9287 runnable_procs:
9289 If a process is put into or removed from the run queue, a
9290 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
9291 erPid. Running processes that are reinserted into the run
9292 queue after having been pre-empted do not trigger this mes‐
9293 sage.
9294 runnable_ports:
9296 If a port is put into or removed from the run queue, a mes‐
9297 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
9298 scheduler:
9300 If a scheduler is put to sleep or awoken, a message, {pro‐
9301 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
9302 filerPid.
9303 strict_monotonic_timestamp:
9305 Time stamps in profile messages consist of Erlang monotonic
9306 time and a monotonically increasing integer. The time stamp
9307 (Ts) has the same format and value as produced by {er‐
9308 lang:monotonic_time(nanosecond), erlang:unique_inte‐
9309 ger([monotonic])}.
9310 timestamp:
9312 Time stamps in profile messages include a time stamp (Ts)
9313 that has the same form as returned by erlang:now(). This is
9314 also the default if no time stamp flag is specified. If
9315 cpu_timestamp has been enabled through erlang:trace/3, this
9316 also effects the time stamp produced in profiling messages
9317 when flag timestamp is enabled.
9318 Note:
9320 erlang:system_profile behavior can change in a future release.
9321 erlang:system_time() -> integer()
9324 Returns current Erlang system time in native time unit.
9326 Calling erlang:system_time() is equivalent to erlang:mono‐
9328 tonic_time() + erlang:time_offset().
9329 Note:
9331 This time is not a monotonically increasing time in the general
9332 case. For more information, see the documentation of time warp
9333 modes in the User's Guide.
9334 erlang:system_time(Unit) -> integer()
9337 Types:
9339 Unit = time_unit()
9341 Returns current Erlang system time converted into the Unit
9343 passed as argument.
9344 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
9346 vert_time_unit(erlang:system_time(), native, Unit).
9347 Note:
9349 This time is not a monotonically increasing time in the general
9350 case. For more information, see the documentation of time warp
9351 modes in the User's Guide.
9352 term_to_binary(Term) -> ext_binary()
9355 Types:
9357 Term = term()
9359 Returns a binary data object that is the result of encoding Term
9361 according to the Erlang external term format.
9362 This can be used for various purposes, for example, writing a
9364 term to a file in an efficient way, or sending an Erlang term to
9365 some type of communications channel not supported by distributed
9366 Erlang.
9367 > Bin = term_to_binary(hello).
9369 <<131,100,0,5,104,101,108,108,111>>
9370 > hello = binary_to_term(Bin).
9371 hello
9372 See also binary_to_term/1.
9375 Note:
9377 There is no guarantee that this function will return the same
9378 encoded representation for the same term.
9379 term_to_binary(Term, Options) -> ext_binary()
9382 Types:
9384 Term = term()
9386 Options =
9387 [compressed |
9388 {compressed, Level :: 0..9} |
9389 {minor_version, Version :: 0..2}]
9390 Returns a binary data object that is the result of encoding Term
9392 according to the Erlang external term format.
9393 If option compressed is provided, the external term format is
9395 compressed. The compressed format is automatically recognized by
9396 binary_to_term/1 as from Erlang/OTP R7B.
9397 A compression level can be specified by giving option {com‐
9399 pressed, Level}. Level is an integer with range 0..9, where:
9400 * 0 - No compression is done (it is the same as giving no com‐
9402 pressed option).
9403 * 1 - Takes least time but may not compress as well as the
9405 higher levels.
9406 * 6 - Default level when option compressed is provided.
9408 * 9 - Takes most time and tries to produce a smaller result.
9410 Notice "tries" in the preceding sentence; depending on the
9411 input term, level 9 compression either does or does not pro‐
9412 duce a smaller result than level 1 compression.
9413 Option {minor_version, Version} can be used to control some en‐
9415 coding details. This option was introduced in Erlang/OTP R11B-4.
9416 The valid values for Version are:
9417 0:
9419 Floats are encoded using a textual representation. This op‐
9420 tion is useful to ensure that releases before Erlang/OTP
9421 R11B-4 can decode resulting binary.
9422 This version encode atoms that can be represented by a
9424 latin1 string using latin1 encoding while only atoms that
9425 cannot be represented by latin1 are encoded using utf8.
9426 1:
9428 This is as of Erlang/OTP 17.0 the default. It forces any
9429 floats in the term to be encoded in a more space-efficient
9430 and exact way (namely in the 64-bit IEEE format, rather than
9431 converted to a textual representation). As from Erlang/OTP
9432 R11B-4, binary_to_term/1 can decode this representation.
9433 This version encode atoms that can be represented by a
9435 latin1 string using latin1 encoding while only atoms that
9436 cannot be represented by latin1 are encoded using utf8.
9437 2:
9439 Drops usage of the latin1 atom encoding and unconditionally
9440 use utf8 encoding for all atoms. This will be changed to the
9441 default in a future major release of Erlang/OTP. Erlang/OTP
9442 systems as of R16B can decode this representation.
9443 See also binary_to_term/1.
9445 term_to_iovec(Term) -> ext_iovec()
9447 Types:
9449 Term = term()
9451 Returns the encoding of Term according to the Erlang external
9453 term format as ext_iovec().
9454 This function produce the same encoding as term_to_binary/1, but
9456 with another return type. The call iolist_to_bi‐
9457 nary(term_to_iovec(Term)) will produce exactly the same result
9458 as the call term_to_binary(Term).
9459 term_to_iovec() is a pure optimization of the functionality
9461 term_to_binary() provide. term_to_iovec() can for example refer
9462 directly to off heap binaries instead of copying the binary data
9463 into the result.
9464 See also term_to_binary/1.
9466 term_to_iovec(Term, Options) -> ext_iovec()
9468 Types:
9470 Term = term()
9472 Options =
9473 [compressed |
9474 {compressed, Level :: 0..9} |
9475 {minor_version, Version :: 0..2}]
9476 Returns the encoding of Term according to the Erlang external
9478 term format as ext_iovec().
9479 This function produce the same encoding as term_to_binary/2, but
9481 with another return type. The call iolist_to_bi‐
9482 nary(term_to_iovec(Term, Opts)) will produce exactly the same
9483 result as term_to_binary(Term, Opts).
9484 Currently recognised options are all options recognised by
9486 term_to_binary/2.
9487 term_to_iovec() is a pure optimization of the functionality
9489 term_to_binary() provide. term_to_iovec() can for example refer
9490 directly to off heap binaries instead of copying the binary data
9491 into the result.
9492 See also term_to_binary/2.
9494 throw(Any) -> no_return()
9496 Types:
9498 Any = term()
9500 A non-local return from a function. If evaluated within a catch,
9502 catch returns value Any. Example:
9503 > catch throw({hello, there}).
9505 {hello,there}
9506 Failure: nocatch if not evaluated within a catch.
9508 time() -> Time
9510 Types:
9512 Time = calendar:time()
9514 Returns the current time as {Hour, Minute, Second}.
9516 The time zone and Daylight Saving Time correction depend on the
9518 underlying OS. Example:
9519 > time().
9521 {9,42,44}
9522 erlang:time_offset() -> integer()
9524 Returns the current time offset between Erlang monotonic time
9526 and Erlang system time in native time unit. Current time offset
9527 added to an Erlang monotonic time gives corresponding Erlang
9528 system time.
9529 The time offset may or may not change during operation depending
9531 on the time warp mode used.
9532 Note:
9534 A change in time offset can be observed at slightly different
9535 points in time by different processes.
9536 If the runtime system is in multi-time warp mode, the time off‐
9538 set is changed when the runtime system detects that the OS sys‐
9539 tem time has changed. The runtime system will, however, not de‐
9540 tect this immediately when it occurs. A task checking the time
9541 offset is scheduled to execute at least once a minute; so, under
9542 normal operation this is to be detected within a minute, but
9543 during heavy load it can take longer time.
9544 erlang:time_offset(Unit) -> integer()
9547 Types:
9549 Unit = time_unit()
9551 Returns the current time offset between Erlang monotonic time
9553 and Erlang system time converted into the Unit passed as argu‐
9554 ment.
9555 Same as calling erlang:convert_time_unit(erlang:time_offset(),
9557 native, Unit) however optimized for commonly used Units.
9558 erlang:timestamp() -> Timestamp
9560 Types:
9562 Timestamp = timestamp()
9564 timestamp() =
9565 {MegaSecs :: integer() >= 0,
9566 Secs :: integer() >= 0,
9567 MicroSecs :: integer() >= 0}
9568 Returns current Erlang system time on the format {MegaSecs,
9570 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
9571 the deprecated erlang:now/0 use. The reason for the existence of
9572 erlang:timestamp() is purely to simplify use for existing code
9573 that assumes this time stamp format. Current Erlang system time
9574 can more efficiently be retrieved in the time unit of your
9575 choice using erlang:system_time/1.
9576 The erlang:timestamp() BIF is equivalent to:
9578 timestamp() ->
9580 ErlangSystemTime = erlang:system_time(microsecond),
9581 MegaSecs = ErlangSystemTime div 1000_000_000_000,
9582 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
9583 MicroSecs = ErlangSystemTime rem 1000_000,
9584 {MegaSecs, Secs, MicroSecs}.
9585 It, however, uses a native implementation that does not build
9587 garbage on the heap and with slightly better performance.
9588 Note:
9590 This time is not a monotonically increasing time in the general
9591 case. For more information, see the documentation of time warp
9592 modes in the User's Guide.
9593 tl(List) -> term()
9596 Types:
9598 List = [term(), ...]
9600 Returns the tail of List, that is, the list minus the first ele‐
9602 ment, for example:
9603 > tl([geesties, guilies, beasties]).
9605 [guilies, beasties]
9606 Allowed in guard tests.
9608 Failure: badarg if List is the empty list [].
9610 erlang:trace(PidPortSpec, How, FlagList) -> integer()
9612 Types:
9614 PidPortSpec =
9616 pid() |
9617 port() |
9618 all | processes | ports | existing | existing_processes |
9619 existing_ports | new | new_processes | new_ports
9620 How = boolean()
9621 FlagList = [trace_flag()]
9622 trace_flag() =
9623 all | send | 'receive' | procs | ports | call | arity |
9624 return_to | silent | running | exiting | running_procs |
9625 running_ports | garbage_collection | timestamp |
9626 cpu_timestamp | monotonic_timestamp |
9627 strict_monotonic_timestamp | set_on_spawn |
9628 set_on_first_spawn | set_on_link | set_on_first_link |
9629 {tracer, pid() | port()} |
9630 {tracer, module(), term()}
9631 Turns on (if How == true) or off (if How == false) the trace
9633 flags in FlagList for the process or processes represented by
9634 PidPortSpec.
9635 PidPortSpec is either a process identifier (pid) for a local
9637 process, a port identifier, or one of the following atoms:
9638 all:
9640 All currently existing processes and ports and all that will
9641 be created in the future.
9642 processes:
9644 All currently existing processes and all that will be cre‐
9645 ated in the future.
9646 ports:
9648 All currently existing ports and all that will be created in
9649 the future.
9650 existing:
9652 All currently existing processes and ports.
9653 existing_processes:
9655 All currently existing processes.
9656 existing_ports:
9658 All currently existing ports.
9659 new:
9661 All processes and ports that will be created in the future.
9662 new_processes:
9664 All processes that will be created in the future.
9665 new_ports:
9667 All ports that will be created in the future.
9668 FlagList can contain any number of the following flags (the
9670 "message tags" refers to the list of trace messages):
9671 all:
9673 Sets all trace flags except tracer and cpu_timestamp, which
9674 are in their nature different than the others.
9675 send:
9677 Traces sending of messages.
9678 Message tags: send and send_to_non_existing_process.
9680 'receive':
9682 Traces receiving of messages.
9683 Message tags: 'receive'.
9685 call:
9687 Traces certain function calls. Specify which function calls
9688 to trace by calling erlang:trace_pattern/3.
9689 Message tags: call and return_from.
9691 silent:
9693 Used with the call trace flag. The call, return_from, and
9694 return_to trace messages are inhibited if this flag is set,
9695 but they are executed as normal if there are match specifi‐
9696 cations.
9697 Silent mode is inhibited by executing erlang:trace(_, false,
9699 [silent|_]), or by a match specification executing the func‐
9700 tion {silent, false}.
9701 The silent trace flag facilitates setting up a trace on many
9703 or even all processes in the system. The trace can then be
9704 activated and deactivated using the match specification
9705 function {silent,Bool}, giving a high degree of control of
9706 which functions with which arguments that trigger the trace.
9707 Message tags: call, return_from, and return_to. Or rather,
9709 the absence of.
9710 return_to:
9712 Used with the call trace flag. Traces the return from a
9713 traced function back to its caller. Only works for functions
9714 traced with option local to erlang:trace_pattern/3.
9715 The semantics is that a trace message is sent when a call
9717 traced function returns, that is, when a chain of tail re‐
9718 cursive calls ends. Only one trace message is sent per chain
9719 of tail recursive calls, so the properties of tail recur‐
9720 siveness for function calls are kept while tracing with this
9721 flag. Using call and return_to trace together makes it pos‐
9722 sible to know exactly in which function a process executes
9723 at any time.
9724 To get trace messages containing return values from func‐
9726 tions, use the {return_trace} match specification action in‐
9727 stead.
9728 Message tags: return_to.
9730 procs:
9732 Traces process-related events.
9733 Message tags: spawn, spawned, exit, register, unregister,
9735 link, unlink, getting_linked, and getting_unlinked.
9736 ports:
9738 Traces port-related events.
9739 Message tags: open, closed, register, unregister, get‐
9741 ting_linked, and getting_unlinked.
9742 running:
9744 Traces scheduling of processes.
9745 Message tags: in and out.
9747 exiting:
9749 Traces scheduling of exiting processes.
9750 Message tags: in_exiting, out_exiting, and out_exited.
9752 running_procs:
9754 Traces scheduling of processes just like running. However,
9755 this option also includes schedule events when the process
9756 executes within the context of a port without being sched‐
9757 uled out itself.
9758 Message tags: in and out.
9760 running_ports:
9762 Traces scheduling of ports.
9763 Message tags: in and out.
9765 garbage_collection:
9767 Traces garbage collections of processes.
9768 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
9770 nor_end.
9771 timestamp:
9773 Includes a time stamp in all trace messages. The time stamp
9774 (Ts) has the same form as returned by erlang:now().
9775 cpu_timestamp:
9777 A global trace flag for the Erlang node that makes all trace
9778 time stamps using flag timestamp to be in CPU time, not wall
9779 clock time. That is, cpu_timestamp is not be used if mono‐
9780 tonic_timestamp or strict_monotonic_timestamp is enabled.
9781 Only allowed with PidPortSpec==all. If the host machine OS
9782 does not support high-resolution CPU time measurements,
9783 trace/3 exits with badarg. Notice that most OS do not syn‐
9784 chronize this value across cores, so be prepared that time
9785 can seem to go backwards when using this option.
9786 monotonic_timestamp:
9788 Includes an Erlang monotonic time time stamp in all trace
9789 messages. The time stamp (Ts) has the same format and value
9790 as produced by erlang:monotonic_time(nanosecond). This flag
9791 overrides flag cpu_timestamp.
9792 strict_monotonic_timestamp:
9794 Includes an time stamp consisting of Erlang monotonic time
9795 and a monotonically increasing integer in all trace mes‐
9796 sages. The time stamp (Ts) has the same format and value as
9797 produced by { erlang:monotonic_time(nanosecond), er‐
9798 lang:unique_integer([monotonic])}. This flag overrides flag
9799 cpu_timestamp.
9800 arity:
9802 Used with the call trace flag. {M, F, Arity} is specified
9803 instead of {M, F, Args} in call trace messages.
9804 set_on_spawn:
9806 Makes any process created by a traced process inherit its
9807 trace flags, including flag set_on_spawn.
9808 set_on_first_spawn:
9810 Makes the first process created by a traced process inherit
9811 its trace flags, excluding flag set_on_first_spawn.
9812 set_on_link:
9814 Makes any process linked by a traced process inherit its
9815 trace flags, including flag set_on_link.
9816 set_on_first_link:
9818 Makes the first process linked to by a traced process in‐
9819 herit its trace flags, excluding flag set_on_first_link.
9820 {tracer, Tracer}:
9822 Specifies where to send the trace messages. Tracer must be
9823 the process identifier of a local process or the port iden‐
9824 tifier of a local port.
9825 {tracer, TracerModule, TracerState}:
9827 Specifies that a tracer module is to be called instead of
9828 sending a trace message. The tracer module can then ignore
9829 or change the trace message. For more details on how to
9830 write a tracer module, see erl_tracer(3).
9831 If no tracer is specified, the calling process receives all the
9833 trace messages.
9834 The effect of combining set_on_first_link with set_on_link is
9836 the same as set_on_first_link alone. Likewise for set_on_spawn
9837 and set_on_first_spawn.
9838 The tracing process receives the trace messages described in the
9840 following list. Pid is the process identifier of the traced
9841 process in which the traced event has occurred. The third tuple
9842 element is the message tag.
9843 If flag timestamp, strict_monotonic_timestamp, or mono‐
9845 tonic_timestamp is specified, the first tuple element is
9846 trace_ts instead, and the time stamp is added as an extra ele‐
9847 ment last in the message tuple. If multiple time stamp flags are
9848 passed, timestamp has precedence over strict_monotonic_time‐
9849 stamp, which in turn has precedence over monotonic_timestamp.
9850 All time stamp flags are remembered, so if two are passed and
9851 the one with highest precedence later is disabled, the other one
9852 becomes active.
9853 If a match specification (applicable only for call, send and
9855 'receive' tracing) contains a {message} action function with a
9856 non-boolean value, that value is added as an extra element to
9857 the message tuple either in the last position or before the
9858 timestamp (if it is present).
9859 Trace messages:
9861 {trace, PidPort, send, Msg, To}:
9863 When PidPort sends message Msg to process To.
9864 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9866 When PidPort sends message Msg to the non-existing process
9867 To.
9868 {trace, PidPort, 'receive', Msg}:
9870 When PidPort receives message Msg. If Msg is set to time-
9871 out, a receive statement can have timed out, or the process
9872 received a message with the payload timeout.
9873 {trace, Pid, call, {M, F, Args}}:
9875 When Pid calls a traced function. The return values of calls
9876 are never supplied, only the call and its arguments.
9877 Trace flag arity can be used to change the contents of this
9879 message, so that Arity is specified instead of Args.
9880 {trace, Pid, return_to, {M, F, Arity}}:
9882 When Pid returns to the specified function. This trace mes‐
9883 sage is sent if both the flags call and return_to are set,
9884 and the function is set to be traced on local function
9885 calls. The message is only sent when returning from a chain
9886 of tail recursive function calls, where at least one call
9887 generated a call trace message (that is, the functions match
9888 specification matched, and {message, false} was not an ac‐
9889 tion).
9890 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9892 When Pid returns from the specified function. This trace
9893 message is sent if flag call is set, and the function has a
9894 match specification with a return_trace or exception_trace
9895 action.
9896 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9898 When Pid exits from the specified function because of an ex‐
9899 ception. This trace message is sent if flag call is set, and
9900 the function has a match specification with an excep‐
9901 tion_trace action.
9902 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9904 When Pid spawns a new process Pid2 with the specified func‐
9905 tion call as entry point.
9906 Args is supposed to be the argument list, but can be any
9908 term if the spawn is erroneous.
9909 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9911 When Pid is spawned by process Pid2 with the specified func‐
9912 tion call as entry point.
9913 Args is supposed to be the argument list, but can be any
9915 term if the spawn is erroneous.
9916 {trace, Pid, exit, Reason}:
9918 When Pid exits with reason Reason.
9919 {trace, PidPort, register, RegName}:
9921 When PidPort gets the name RegName registered.
9922 {trace, PidPort, unregister, RegName}:
9924 When PidPort gets the name RegName unregistered. This is
9925 done automatically when a registered process or port exits.
9926 {trace, Pid, link, Pid2}:
9928 When Pid links to a process Pid2.
9929 {trace, Pid, unlink, Pid2}:
9931 When Pid removes the link from a process Pid2.
9932 {trace, PidPort, getting_linked, Pid2}:
9934 When PidPort gets linked to a process Pid2.
9935 {trace, PidPort, getting_unlinked, Pid2}:
9937 When PidPort gets unlinked from a process Pid2.
9938 {trace, Pid, exit, Reason}:
9940 When Pid exits with reason Reason.
9941 {trace, Port, open, Pid, Driver}:
9943 When Pid opens a new port Port with the running Driver.
9944 Driver is the name of the driver as an atom.
9946 {trace, Port, closed, Reason}:
9948 When Port closes with Reason.
9949 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9951 When Pid is scheduled to run. The process runs in function
9952 {M, F, Arity}. On some rare occasions, the current function
9953 cannot be determined, then the last element is 0.
9954 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9956 0}:
9957 When Pid is scheduled out. The process was running in func‐
9958 tion {M, F, Arity}. On some rare occasions, the current
9959 function cannot be determined, then the last element is 0.
9960 {trace, Port, in, Command | 0}:
9962 When Port is scheduled to run. Command is the first thing
9963 the port will execute, it can however run several commands
9964 before being scheduled out. On some rare occasions, the cur‐
9965 rent function cannot be determined, then the last element is
9966 0.
9967 The possible commands are call, close, command, connect,
9969 control, flush, info, link, open, and unlink.
9970 {trace, Port, out, Command | 0}:
9972 When Port is scheduled out. The last command run was Com‐
9973 mand. On some rare occasions, the current function cannot be
9974 determined, then the last element is 0. Command can contain
9975 the same commands as in
9976 {trace, Pid, gc_minor_start, Info}:
9978 Sent when a young garbage collection is about to be started.
9981 Info is a list of two-element tuples, where the first ele‐
9982 ment is a key, and the second is the value. Do not depend on
9983 any order of the tuples. The following keys are defined:
9984 heap_size:
9986 The size of the used part of the heap.
9987 heap_block_size:
9989 The size of the memory block used for storing the heap and
9990 the stack.
9991 old_heap_size:
9993 The size of the used part of the old heap.
9994 old_heap_block_size:
9996 The size of the memory block used for storing the old
9997 heap.
9998 stack_size:
10000 The size of the stack.
10001 recent_size:
10003 The size of the data that survived the previous garbage
10004 collection.
10005 mbuf_size:
10007 The combined size of message buffers associated with the
10008 process.
10009 bin_vheap_size:
10011 The total size of unique off-heap binaries referenced from
10012 the process heap.
10013 bin_vheap_block_size:
10015 The total size of binaries allowed in the virtual heap in
10016 the process before doing a garbage collection.
10017 bin_old_vheap_size:
10019 The total size of unique off-heap binaries referenced from
10020 the process old heap.
10021 bin_old_vheap_block_size:
10023 The total size of binaries allowed in the virtual old heap
10024 in the process before doing a garbage collection.
10025 All sizes are in words.
10027 {trace, Pid, gc_max_heap_size, Info}:
10029 Sent when the max_heap_size is reached during garbage col‐
10030 lection. Info contains the same kind of list as in message
10031 gc_start, but the sizes reflect the sizes that triggered
10032 max_heap_size to be reached.
10033 {trace, Pid, gc_minor_end, Info}:
10035 Sent when young garbage collection is finished. Info con‐
10036 tains the same kind of list as in message gc_minor_start,
10037 but the sizes reflect the new sizes after garbage collec‐
10038 tion.
10039 {trace, Pid, gc_major_start, Info}:
10041 Sent when fullsweep garbage collection is about to be
10042 started. Info contains the same kind of list as in message
10043 gc_minor_start.
10044 {trace, Pid, gc_major_end, Info}:
10046 Sent when fullsweep garbage collection is finished. Info
10047 contains the same kind of list as in message gc_minor_start,
10048 but the sizes reflect the new sizes after a fullsweep
10049 garbage collection.
10050 If the tracing process/port dies or the tracer module returns
10052 remove, the flags are silently removed.
10053 Each process can only be traced by one tracer. Therefore, at‐
10055 tempts to trace an already traced process fail.
10056 Returns a number indicating the number of processes that matched
10058 PidPortSpec. If PidPortSpec is a process identifier, the return
10059 value is 1. If PidPortSpec is all or existing, the return value
10060 is the number of processes running. If PidPortSpec is new, the
10061 return value is 0.
10062 Failure: badarg if the specified arguments are not supported.
10064 For example, cpu_timestamp is not supported on all platforms.
10065 erlang:trace_delivered(Tracee) -> Ref
10067 Types:
10069 Tracee = pid() | all
10071 Ref = reference()
10072 The delivery of trace messages (generated by erlang:trace/3,
10074 seq_trace(3), or erlang:system_profile/2) is dislocated on the
10075 time-line compared to other events in the system. If you know
10076 that Tracee has passed some specific point in its execution, and
10077 you want to know when at least all trace messages corresponding
10078 to events up to this point have reached the tracer, use er‐
10079 lang:trace_delivered(Tracee).
10080 When it is guaranteed that all trace messages are delivered to
10082 the tracer up to the point that Tracee reached at the time of
10083 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
10084 ered, Tracee, Ref} message is sent to the caller of er‐
10085 lang:trace_delivered(Tracee) .
10086 Notice that message trace_delivered does not imply that trace
10088 messages have been delivered. Instead it implies that all trace
10089 messages that are to be delivered have been delivered. It is not
10090 an error if Tracee is not, and has not been traced by someone,
10091 but if this is the case, no trace messages have been delivered
10092 when the trace_delivered message arrives.
10093 Notice that Tracee must refer to a process currently or previ‐
10095 ously existing on the same node as the caller of er‐
10096 lang:trace_delivered(Tracee) resides on. The special Tracee atom
10097 all denotes all processes that currently are traced in the node.
10098 When used together with a Tracer Module, any message sent in
10100 the trace callback is guaranteed to have reached its recipient
10101 before the trace_delivered message is sent.
10102 Example: Process A is Tracee, port B is tracer, and process C is
10104 the port owner of B. C wants to close B when A exits. To ensure
10105 that the trace is not truncated, C can call erlang:trace_deliv‐
10106 ered(A) when A exits, and wait for message {trace_delivered, A,
10107 Ref} before closing B.
10108 Failure: badarg if Tracee does not refer to a process (dead or
10110 alive) on the same node as the caller of erlang:trace_deliv‐
10111 ered(Tracee) resides on.
10112 erlang:trace_info(PidPortFuncEvent, Item) -> Res
10114 Types:
10116 PidPortFuncEvent =
10118 pid() |
10119 port() |
10120 new | new_processes | new_ports |
10121 {Module, Function, Arity} |
10122 on_load | send | 'receive'
10123 Module = module()
10124 Function = atom()
10125 Arity = arity()
10126 Item =
10127 flags | tracer | traced | match_spec | meta |
10128 meta_match_spec | call_count | call_time | all
10129 Res = trace_info_return()
10130 trace_info_return() =
10131 undefined |
10132 {flags, [trace_info_flag()]} |
10133 {tracer, pid() | port() | []} |
10134 {tracer, module(), term()} |
10135 trace_info_item_result() |
10136 {all, [trace_info_item_result()] | false | undefined}
10137 trace_info_item_result() =
10138 {traced, global | local | false | undefined} |
10139 {match_spec, trace_match_spec() | false | undefined} |
10140 {meta, pid() | port() | false | undefined | []} |
10141 {meta, module(), term()} |
10142 {meta_match_spec, trace_match_spec() | false | undefined} |
10143 {call_count, integer() >= 0 | boolean() | undefined} |
10144 {call_time,
10145 [{pid(),
10146 integer() >= 0,
10147 integer() >= 0,
10148 integer() >= 0}] |
10149 boolean() |
10150 undefined}
10151 trace_info_flag() =
10152 send | 'receive' | set_on_spawn | call | return_to | procs |
10153 set_on_first_spawn | set_on_link | running |
10154 garbage_collection | timestamp | monotonic_timestamp |
10155 strict_monotonic_timestamp | arity
10156 trace_match_spec() =
10157 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10158 match_variable() = atom()
10159 Approximation of '$1' | '$2' | '$3' | ...
10160 Returns trace information about a port, process, function, or
10162 event.
10163 To get information about a port or process, PidPortFuncEvent is
10165 to be a process identifier (pid), port identifier, or one of the
10166 atoms new, new_processes, or new_ports. The atom new or new_pro‐
10167 cesses means that the default trace state for processes to be
10168 created is returned. The atom new_ports means that the default
10169 trace state for ports to be created is returned.
10170 Valid Items for ports and processes:
10172 flags:
10174 Returns a list of atoms indicating what kind of traces is
10175 enabled for the process. The list is empty if no traces are
10176 enabled, and one or more of the followings atoms if traces
10177 are enabled: send, 'receive', set_on_spawn, call, return_to,
10178 procs, ports, set_on_first_spawn, set_on_link, running, run‐
10179 ning_procs, running_ports, silent, exiting, monotonic_time‐
10180 stamp, strict_monotonic_timestamp, garbage_collection, time‐
10181 stamp, and arity. The order is arbitrary.
10182 tracer:
10184 Returns the identifier for process, port, or a tuple con‐
10185 taining the tracer module and tracer state tracing this
10186 process. If this process is not traced, the return value is
10187 [].
10188 To get information about a function, PidPortFuncEvent is to be
10190 the three-element tuple {Module, Function, Arity} or the atom
10191 on_load. No wildcards are allowed. Returns undefined if the
10192 function does not exist, or false if the function is not traced.
10193 If PidPortFuncEvent is on_load, the information returned refers
10194 to the default value for code that will be loaded.
10195 Valid Items for functions:
10197 traced:
10199 Returns global if this function is traced on global function
10200 calls, local if this function is traced on local function
10201 calls (that is, local and global function calls), and false
10202 if local or global function calls are not traced.
10203 match_spec:
10205 Returns the match specification for this function, if it has
10206 one. If the function is locally or globally traced but has
10207 no match specification defined, the returned value is [].
10208 meta:
10210 Returns the meta-trace tracer process, port, or trace module
10211 for this function, if it has one. If the function is not
10212 meta-traced, the returned value is false. If the function is
10213 meta-traced but has once detected that the tracer process is
10214 invalid, the returned value is [].
10215 meta_match_spec:
10217 Returns the meta-trace match specification for this func‐
10218 tion, if it has one. If the function is meta-traced but has
10219 no match specification defined, the returned value is [].
10220 call_count:
10222 Returns the call count value for this function or true for
10223 the pseudo function on_load if call count tracing is active.
10224 Otherwise false is returned.
10225 See also erlang:trace_pattern/3.
10227 call_time:
10229 Returns the call time values for this function or true for
10230 the pseudo function on_load if call time tracing is active.
10231 Otherwise false is returned. The call time values returned,
10232 [{Pid, Count, S, Us}], is a list of each process that exe‐
10233 cuted the function and its specific counters.
10234 See also erlang:trace_pattern/3.
10236 all:
10238 Returns a list containing the {Item, Value} tuples for all
10239 other items, or returns false if no tracing is active for
10240 this function.
10241 To get information about an event, PidPortFuncEvent is to be one
10243 of the atoms send or 'receive'.
10244 One valid Item for events exists:
10246 match_spec:
10248 Returns the match specification for this event, if it has
10249 one, or true if no match specification has been set.
10250 The return value is {Item, Value}, where Value is the requested
10252 information as described earlier. If a pid for a dead process
10253 was specified, or the name of a non-existing function, Value is
10254 undefined.
10255 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
10257 Types:
10259 MFA = trace_pattern_mfa() | send | 'receive'
10261 MatchSpec =
10262 (MatchSpecList :: trace_match_spec()) |
10263 boolean() |
10264 restart | pause
10265 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
10266 trace_match_spec() =
10267 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10268 match_variable() = atom()
10269 Approximation of '$1' | '$2' | '$3' | ...
10270 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
10272 for backward compatibility.
10273 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
10275 integer() >= 0
10276 Types:
10278 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
10280 trace_match_spec() =
10281 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10282 match_variable() = atom()
10283 Approximation of '$1' | '$2' | '$3' | ...
10284 Sets trace pattern for message sending. Must be combined with
10286 erlang:trace/3 to set the send trace flag for one or more pro‐
10287 cesses. By default all messages sent from send traced processes
10288 are traced. To limit traced send events based on the message
10289 content, the sender and/or the receiver, use erlang:trace_pat‐
10290 tern/3.
10291 Argument MatchSpec can take the following forms:
10293 MatchSpecList:
10295 A list of match specifications. The matching is done on the
10296 list [Receiver, Msg]. Receiver is the process or port iden‐
10297 tity of the receiver and Msg is the message term. The pid of
10298 the sending process can be accessed with the guard function
10299 self/0. An empty list is the same as true. For more informa‐
10300 tion, see section Match Specifications in Erlang in the
10301 User's Guide.
10302 true:
10304 Enables tracing for all sent messages (from send traced pro‐
10305 cesses). Any match specification is removed. This is the de‐
10306 fault.
10307 false:
10309 Disables tracing for all sent messages. Any match specifica‐
10310 tion is removed.
10311 Argument FlagList must be [] for send tracing.
10313 The return value is always 1.
10315 Examples:
10317 Only trace messages to a specific process Pid:
10319 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
10321 1
10322 Only trace messages matching {reply, _}:
10324 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
10326 1
10327 Only trace messages sent to the sender itself:
10329 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
10331 1
10332 Only trace messages sent to other nodes:
10334 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
10336 1
10337 Note:
10339 A match specification for send trace can use all guard and body
10340 functions except caller.
10341 Fails by raising an error exception with an error reason of:
10344 badarg:
10346 If an argument is invalid.
10347 system_limit:
10349 If a match specification passed as argument has excessive
10350 nesting which causes scheduler stack exhaustion for the
10351 scheduler that the calling process is executing on. Sched‐
10352 uler stack size can be configured when starting the runtime
10353 system.
10354 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
10356 integer() >= 0
10357 Types:
10359 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
10361 trace_match_spec() =
10362 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10363 match_variable() = atom()
10364 Approximation of '$1' | '$2' | '$3' | ...
10365 Sets trace pattern for message receiving. Must be combined with
10367 erlang:trace/3 to set the 'receive' trace flag for one or more
10368 processes. By default all messages received by 'receive' traced
10369 processes are traced. To limit traced receive events based on
10370 the message content, the sender and/or the receiver, use er‐
10371 lang:trace_pattern/3.
10372 Argument MatchSpec can take the following forms:
10374 MatchSpecList:
10376 A list of match specifications. The matching is done on the
10377 list [Node, Sender, Msg]. Node is the node name of the
10378 sender. Sender is the process or port identity of the
10379 sender, or the atom undefined if the sender is not known
10380 (which can be the case for remote senders). Msg is the mes‐
10381 sage term. The pid of the receiving process can be accessed
10382 with the guard function self/0. An empty list is the same as
10383 true. For more information, see section Match Specifica‐
10384 tions in Erlang in the User's Guide.
10385 true:
10387 Enables tracing for all received messages (to 'receive'
10388 traced processes). Any match specification is removed. This
10389 is the default.
10390 false:
10392 Disables tracing for all received messages. Any match speci‐
10393 fication is removed.
10394 Argument FlagList must be [] for receive tracing.
10396 The return value is always 1.
10398 Examples:
10400 Only trace messages from a specific process Pid:
10402 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
10404 1
10405 Only trace messages matching {reply, _}:
10407 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
10409 1
10410 Only trace messages from other nodes:
10412 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
10414 1
10415 Note:
10417 A match specification for 'receive' trace can use all guard and
10418 body functions except caller, is_seq_trace, get_seq_token,
10419 set_seq_token, enable_trace, disable_trace, trace, silent, and
10420 process_dump.
10421 Fails by raising an error exception with an error reason of:
10424 badarg:
10426 If an argument is invalid.
10427 system_limit:
10429 If a match specification passed as argument has excessive
10430 nesting which causes scheduler stack exhaustion for the
10431 scheduler that the calling process is executing on. Sched‐
10432 uler stack size can be configured when starting the runtime
10433 system.
10434 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
10436 integer() >= 0
10437 Types:
10439 MFA = trace_pattern_mfa()
10441 MatchSpec =
10442 (MatchSpecList :: trace_match_spec()) |
10443 boolean() |
10444 restart | pause
10445 FlagList = [trace_pattern_flag()]
10446 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
10447 trace_match_spec() =
10448 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10449 trace_pattern_flag() =
10450 global | local | meta |
10451 {meta, Pid :: pid()} |
10452 {meta, TracerModule :: module(), TracerState :: term()} |
10453 call_count | call_time
10454 match_variable() = atom()
10455 Approximation of '$1' | '$2' | '$3' | ...
10456 Enables or disables call tracing for one or more functions. Must
10458 be combined with erlang:trace/3 to set the call trace flag for
10459 one or more processes.
10460 Conceptually, call tracing works as follows. Inside the Erlang
10462 virtual machine, a set of processes and a set of functions are
10463 to be traced. If a traced process calls a traced function, the
10464 trace action is taken. Otherwise, nothing happens.
10465 To add or remove one or more processes to the set of traced pro‐
10467 cesses, use erlang:trace/3.
10468 To add or remove functions to the set of traced functions, use
10470 erlang:trace_pattern/3.
10471 The BIF erlang:trace_pattern/3 can also add match specifications
10473 to a function. A match specification comprises a pattern that
10474 the function arguments must match, a guard expression that must
10475 evaluate to true, and an action to be performed. The default ac‐
10476 tion is to send a trace message. If the pattern does not match
10477 or the guard fails, the action is not executed.
10478 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
10480 ity}, or the atom on_load (described below). It can be the mod‐
10481 ule, function, and arity for a function (or a BIF in any mod‐
10482 ule). The atom '_' can be used as a wildcard in any of the fol‐
10483 lowing ways:
10484 {Module,Function,'_'}:
10486 All functions of any arity named Function in module Module.
10487 {Module,'_','_'}:
10489 All functions in module Module.
10490 {'_','_','_'}:
10492 All functions in all loaded modules.
10493 Other combinations, such as {Module,'_',Arity}, are not allowed.
10495 Local functions match wildcards only if option local is in
10496 FlagList.
10497 If argument MFA is the atom on_load, the match specification and
10499 flag list are used on all modules that are newly loaded.
10500 Argument MatchSpec can take the following forms:
10502 false:
10504 Disables tracing for the matching functions. Any match spec‐
10505 ification is removed.
10506 true:
10508 Enables tracing for the matching functions. Any match speci‐
10509 fication is removed.
10510 MatchSpecList:
10512 A list of match specifications. An empty list is equivalent
10513 to true. For a description of match specifications, see sec‐
10514 tion Match Specifications in Erlang in the User's Guide.
10515 restart:
10517 For the FlagList options call_count and call_time: restarts
10518 the existing counters. The behavior is undefined for other
10519 FlagList options.
10520 pause:
10522 For the FlagList options call_count and call_time: pauses
10523 the existing counters. The behavior is undefined for other
10524 FlagList options.
10525 Parameter FlagList is a list of options. The following are the
10527 valid options:
10528 global:
10530 Turns on or off call tracing for global function calls (that
10531 is, calls specifying the module explicitly). Only exported
10532 functions match and only global calls generate trace mes‐
10533 sages. This is the default.
10534 local:
10536 Turns on or off call tracing for all types of function
10537 calls. Trace messages are sent whenever any of the specified
10538 functions are called, regardless of how they are called. If
10539 flag return_to is set for the process, a return_to message
10540 is also sent when this function returns to its caller.
10541 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
10543 Turns on or off meta-tracing for all types of function
10544 calls. Trace messages are sent to the tracer whenever any of
10545 the specified functions are called. If no tracer is speci‐
10546 fied, self() is used as a default tracer process.
10547 Meta-tracing traces all processes and does not care about
10549 the process trace flags set by erlang:trace/3, the trace
10550 flags are instead fixed to [call, timestamp].
10551 The match specification function {return_trace} works with
10553 meta-trace and sends its trace message to the same tracer.
10554 call_count:
10556 Starts (MatchSpec == true) or stops (MatchSpec == false)
10557 call count tracing for all types of function calls. For ev‐
10558 ery function, a counter is incremented when the function is
10559 called, in any process. No process trace flags need to be
10560 activated.
10561 If call count tracing is started while already running, the
10563 count is restarted from zero. To pause running counters, use
10564 MatchSpec == pause. Paused and running counters can be
10565 restarted from zero with MatchSpec == restart.
10566 To read the counter value, use erlang:trace_info/2.
10568 call_time:
10570 Starts (MatchSpec == true) or stops (MatchSpec == false)
10571 call time tracing for all types of function calls. For every
10572 function, a counter is incremented when the function is
10573 called. Time spent in the function is accumulated in two
10574 other counters, seconds and microseconds. The counters are
10575 stored for each call traced process.
10576 If call time tracing is started while already running, the
10578 count and time restart from zero. To pause running counters,
10579 use MatchSpec == pause. Paused and running counters can be
10580 restarted from zero with MatchSpec == restart.
10581 To read the counter value, use erlang:trace_info/2.
10583 The options global and local are mutually exclusive, and global
10585 is the default (if no options are specified). The options
10586 call_count and meta perform a kind of local tracing, and cannot
10587 be combined with global. A function can be globally or locally
10588 traced. If global tracing is specified for a set of functions,
10589 then local, meta, call time, and call count tracing for the
10590 matching set of local functions is disabled, and conversely.
10591 When disabling trace, the option must match the type of trace
10593 set on the function. That is, local tracing must be disabled
10594 with option local and global tracing with option global (or no
10595 option), and so on.
10596 Part of a match specification list cannot be changed directly.
10598 If a function has a match specification, it can be replaced with
10599 a new one. To change an existing match specification, use the
10600 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
10601 cation.
10602 Returns the number of functions matching argument MFA. This is
10604 zero if none matched.
10605 Fails by raising an error exception with an error reason of:
10607 badarg:
10609 If an argument is invalid.
10610 system_limit:
10612 If a match specification passed as argument has excessive
10613 nesting which causes scheduler stack exhaustion for the
10614 scheduler that the calling process is executing on. Sched‐
10615 uler stack size can be configured when starting the runtime
10616 system.
10617 trunc(Number) -> integer()
10619 Types:
10621 Number = number()
10623 Returns an integer by truncating Number, for example:
10625 > trunc(5.5).
10627 5
10628 Allowed in guard tests.
10630 tuple_size(Tuple) -> integer() >= 0
10632 Types:
10634 Tuple = tuple()
10636 Returns an integer that is the number of elements in Tuple, for
10638 example:
10639 > tuple_size({morni, mulle, bwange}).
10641 3
10642 Allowed in guard tests.
10644 tuple_to_list(Tuple) -> [term()]
10646 Types:
10648 Tuple = tuple()
10650 Returns a list corresponding to Tuple. Tuple can contain any Er‐
10652 lang terms. Example:
10653 > tuple_to_list({share, {'Ericsson_B', 163}}).
10655 [share,{'Ericsson_B',163}]
10656 erlang:unique_integer() -> integer()
10658 Generates and returns an integer unique on current runtime sys‐
10660 tem instance. The same as calling erlang:unique_integer([]).
10661 erlang:unique_integer(ModifierList) -> integer()
10663 Types:
10665 ModifierList = [Modifier]
10667 Modifier = positive | monotonic
10668 Generates and returns an integer unique on current runtime sys‐
10670 tem instance. The integer is unique in the sense that this BIF,
10671 using the same set of modifiers, does not return the same inte‐
10672 ger more than once on the current runtime system instance. Each
10673 integer value can of course be constructed by other means.
10674 By default, when [] is passed as ModifierList, both negative and
10676 positive integers can be returned. This to use the range of in‐
10677 tegers that do not need heap memory allocation as much as possi‐
10678 ble. By default the returned integers are also only guaranteed
10679 to be unique, that is, any returned integer can be smaller or
10680 larger than previously returned integers.
10681 Modifiers:
10683 positive:
10685 Returns only positive integers.
10686 Notice that by passing the positive modifier you will get
10688 heap allocated integers (bignums) quicker.
10689 monotonic:
10691 Returns strictly monotonically increasing integers corre‐
10692 sponding to creation time. That is, the integer returned is
10693 always larger than previously returned integers on the cur‐
10694 rent runtime system instance.
10695 These values can be used to determine order between events
10697 on the runtime system instance. That is, if both X = er‐
10698 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
10699 ger([monotonic]) are executed by different processes (or the
10700 same process) on the same runtime system instance and X < Y,
10701 we know that X was created before Y.
10702 Warning:
10704 Strictly monotonically increasing values are inherently quite
10705 expensive to generate and scales poorly. This is because the
10706 values need to be synchronized between CPU cores. That is, do
10707 not pass the monotonic modifier unless you really need
10708 strictly monotonically increasing values.
10709 All valid Modifiers can be combined. Repeated (valid) Modifiers
10712 in the ModifierList are ignored.
10713 Note:
10715 The set of integers returned by erlang:unique_integer/1 using
10716 different sets of Modifiers will overlap. For example, by call‐
10717 ing unique_integer([monotonic]), and unique_integer([positive,
10718 monotonic]) repeatedly, you will eventually see some integers
10719 that are returned by both calls.
10720 Failures:
10723 badarg:
10725 if ModifierList is not a proper list.
10726 badarg:
10728 if Modifier is not a valid modifier.
10729 erlang:universaltime() -> DateTime
10731 Types:
10733 DateTime = calendar:datetime()
10735 Returns the current date and time according to Universal Time
10737 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10738 Minute, Second}} if supported by the underlying OS. Otherwise
10739 erlang:universaltime() is equivalent to erlang:localtime(). Ex‐
10740 ample:
10741 > erlang:universaltime().
10743 {{1996,11,6},{14,18,43}}
10744 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10746 Types:
10748 Localtime = Universaltime = calendar:datetime()
10750 Converts Universal Time Coordinated (UTC) date and time to local
10752 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10753 Second}} if supported by the underlying OS. Otherwise no conver‐
10754 sion is done, and Universaltime is returned. Example:
10755 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10757 {{1996,11,7},{15,18,43}}
10758 Failure: badarg if Universaltime denotes an invalid date and
10760 time.
10761 unlink(Id) -> true
10763 Types:
10765 Id = pid() | port()
10767 Removes a link between the calling process and another process
10769 or a port identified by Id. We will from here on call the iden‐
10770 tified process or port unlinkee.
10771 A link can be set up using the link/1 BIF. For more information
10773 on links and exit signals due to links, see the Processes chap‐
10774 ter in the Erlang Reference Manual :
10775 * Links
10777 * Sending Exit Signals
10779 * Receiving Exit Signals
10781 Once unlink(Id) has returned, it is guaranteed that the link be‐
10783 tween the caller and the unlinkee has no effect on the caller in
10784 the future (unless the link is setup again). Note that if the
10785 caller is trapping exits, an {'EXIT', Id, ExitReason} message
10786 due to the link may have been placed in the message queue of the
10787 caller before the unlink(Id) call completed. Also note that the
10788 {'EXIT', Id, ExitReason} message may be the result of the link,
10789 but may also be the result of the unlikee sending the caller an
10790 exit signal by calling the exit/2 BIF. Therefore, it may or may
10791 not be appropriate to clean up the message queue after a call to
10792 unlink(Id) as follows, when trapping exits:
10793 unlink(Id),
10795 receive
10796 {'EXIT', Id, _} ->
10797 true
10798 after 0 ->
10799 true
10800 end
10801 The link removal is performed asynchronously. If such a link
10803 does not exist, nothing is done. A detailed description of the
10804 link protocol can be found in the Distribution Protocol chapter
10805 of the ERTS User's Guide .
10806 Failure: badarg if Id does not identify a process or a node lo‐
10808 cal port.
10809 unregister(RegName) -> true
10811 Types:
10813 RegName = atom()
10815 Removes the registered name RegName associated with a process
10817 identifier or a port identifier, for example:
10818 > unregister(db).
10820 true
10821 Users are advised not to unregister system processes.
10823 Failure: badarg if RegName is not a registered name.
10825 whereis(RegName) -> pid() | port() | undefined
10827 Types:
10829 RegName = atom()
10831 Returns the process identifier or port identifier with the reg‐
10833 istered name RegName. Returns undefined if the name is not reg‐
10834 istered. Example:
10835 > whereis(db).
10837 <0.43.0>
10838 erlang:yield() -> true
10840 Voluntarily lets other processes (if any) get a chance to exe‐
10842 cute. Using this function is similar to receive after 1 -> true
10843 end, except that yield() is faster.
10844 Warning:
10846 There is seldom or never any need to use this BIF as other pro‐
10847 cesses have a chance to run in another scheduler thread anyway.
10848 Using this BIF without a thorough grasp of how the scheduler
10849 works can cause performance degradation.
10850Ericsson AB erts 11.2.2.2 erlang(3)