1erlang(3) Erlang Module Definition erlang(3)
2
3
4
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
15 Auto-imported BIFs are listed without module prefix. BIFs listed with
16 module prefix are not auto-imported.
17
18 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
22 Some BIFs can be used in guard tests and are marked with "Allowed in
23 guard tests".
24
26 ext_binary() = binary()
27
28 A binary data object, structured according to the Erlang exter‐
29 nal term format.
30
31 ext_iovec() = iovec()
32
33 A term of type iovec(), structured according to the Erlang ex‐
34 ternal term format.
35
36 iovec() = [binary()]
37
38 A list of binaries. This datatype is useful to use together with
39 enif_inspect_iovec.
40
41 message_queue_data() = off_heap | on_heap
42
43 See process_flag(message_queue_data, MQD).
44
45 monitor_option() =
46 {alias, explicit_unalias | demonitor | reply_demonitor} |
47 {tag, term()}
48
49 See monitor/3.
50
51 timestamp() =
52 {MegaSecs :: integer() >= 0,
53 Secs :: integer() >= 0,
54 MicroSecs :: integer() >= 0}
55
56 See erlang:timestamp/0.
57
58 time_unit() =
59 integer() >= 1 |
60 second | millisecond | microsecond | nanosecond | native |
61 perf_counter |
62 deprecated_time_unit()
63
64 Supported time unit representations:
65
66 PartsPerSecond :: integer() >= 1:
67 Time unit expressed in parts per second. That is, the time
68 unit equals 1/PartsPerSecond second.
69
70 second:
71 Symbolic representation of the time unit represented by the
72 integer 1.
73
74 millisecond:
75 Symbolic representation of the time unit represented by the
76 integer 1000.
77
78 microsecond:
79 Symbolic representation of the time unit represented by the
80 integer 1000_000.
81
82 nanosecond:
83 Symbolic representation of the time unit represented by the
84 integer 1000_000_000.
85
86 native:
87 Symbolic representation of the native time unit used by the
88 Erlang runtime system.
89
90 The native time unit is determined at runtime system start,
91 and remains the same until the runtime system terminates. If
92 a runtime system is stopped and then started again (even on
93 the same machine), the native time unit of the new runtime
94 system instance can differ from the native time unit of the
95 old runtime system instance.
96
97 One can get an approximation of the native time unit by
98 calling erlang:convert_time_unit(1, second, native). The re‐
99 sult equals the number of whole native time units per sec‐
100 ond. If the number of native time units per second does not
101 add up to a whole number, the result is rounded downwards.
102
103 Note:
104 The value of the native time unit gives you more or less no
105 information about the quality of time values. It sets a limit
106 for the resolution and for the precision of time values, but
107 it gives no information about the accuracy of time values.
108 The resolution of the native time unit and the resolution of
109 time values can differ significantly.
110
111
112 perf_counter:
113 Symbolic representation of the performance counter time unit
114 used by the Erlang runtime system.
115
116 The perf_counter time unit behaves much in the same way as
117 the native time unit. That is, it can differ between runtime
118 restarts. To get values of this type, call
119 os:perf_counter/0.
120
121 deprecated_time_unit():
122 Deprecated symbolic representations kept for backwards-com‐
123 patibility.
124
125 The time_unit/0 type can be extended. To convert time values be‐
126 tween time units, use erlang:convert_time_unit/3.
127
128 deprecated_time_unit() =
129 seconds | milli_seconds | micro_seconds | nano_seconds
130
131 The time_unit() type also consist of the following deprecated
132 symbolic time units:
133
134 seconds:
135 Same as second.
136
137 milli_seconds:
138 Same as millisecond.
139
140 micro_seconds:
141 Same as microsecond.
142
143 nano_seconds:
144 Same as nanosecond.
145
146 dist_handle()
147
148 An opaque handle identifing a distribution channel.
149
150 nif_resource()
151
152 An opaque handle identifing a NIF resource object .
153
154 spawn_opt_option() =
155 link | monitor |
156 {monitor, MonitorOpts :: [monitor_option()]} |
157 {priority, Level :: priority_level()} |
158 {fullsweep_after, Number :: integer() >= 0} |
159 {min_heap_size, Size :: integer() >= 0} |
160 {min_bin_vheap_size, VSize :: integer() >= 0} |
161 {max_heap_size, Size :: max_heap_size()} |
162 {message_queue_data, MQD :: message_queue_data()}
163
164 Options for spawn_opt().
165
166 priority_level() = low | normal | high | max
167
168 Process priority level. For more info see process_flag(priority,
169 Level)
170
171 max_heap_size() =
172 integer() >= 0 |
173 #{size => integer() >= 0,
174 kill => boolean(),
175 error_logger => boolean()}
176
177 Process max heap size configuration. For more info see
178 process_flag(max_heap_size, MaxHeapSize)
179
180 message_queue_data() = off_heap | on_heap
181
182 Process message queue data configuration. For more information,
183 see process_flag(message_queue_data, MQD)
184
185 stacktrace() =
186 [{module(),
187 atom(),
188 arity() | [term()],
189 [stacktrace_extrainfo()]} |
190 {function(), arity() | [term()], [stacktrace_extrainfo()]}]
191
192 stacktrace_extrainfo() =
193 {line, integer() >= 1} |
194 {file, unicode:chardata()} |
195 {error_info,
196 #{module => module(), function => atom(), cause => term()}} |
197 {atom(), term()}
198
199 An Erlang stacktrace as described by Errors and Error Handling
200 section in the Erlang Reference Manual.
201
203 abs(Float) -> float()
204
205 abs(Int) -> integer() >= 0
206
207 Types:
208
209 Int = integer()
210
211 Returns an integer or float that is the arithmetical absolute
212 value of Float or Int, for example:
213
214 > abs(-3.33).
215 3.33
216 > abs(-3).
217 3
218
219 Allowed in guard tests.
220
221 erlang:adler32(Data) -> integer() >= 0
222
223 Types:
224
225 Data = iodata()
226
227 Computes and returns the adler32 checksum for Data.
228
229 erlang:adler32(OldAdler, Data) -> integer() >= 0
230
231 Types:
232
233 OldAdler = integer() >= 0
234 Data = iodata()
235
236 Continues computing the adler32 checksum by combining the previ‐
237 ous checksum, OldAdler, with the checksum of Data.
238
239 The following code:
240
241 X = erlang:adler32(Data1),
242 Y = erlang:adler32(X,Data2).
243
244 assigns the same value to Y as this:
245
246 Y = erlang:adler32([Data1,Data2]).
247
248 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
249 integer() >= 0
250
251 Types:
252
253 FirstAdler = SecondAdler = SecondSize = integer() >= 0
254
255 Combines two previously computed adler32 checksums. This compu‐
256 tation requires the size of the data object for the second
257 checksum to be known.
258
259 The following code:
260
261 Y = erlang:adler32(Data1),
262 Z = erlang:adler32(Y,Data2).
263
264 assigns the same value to Z as this:
265
266 X = erlang:adler32(Data1),
267 Y = erlang:adler32(Data2),
268 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
269
270 alias() -> Alias
271
272 alias(Opts) -> Alias
273
274 Types:
275
276 Alias = reference()
277 Opts = [explicit_unalias | reply]
278
279 Create an alias which can be used when sending messages to the
280 process that created the alias. When the alias has been deacti‐
281 vated, messages sent using the alias will be dropped. An alias
282 can be deactivated using unalias/1. Currently available options
283 for alias/1:
284
285 explicit_unalias:
286 The alias can only be deactivated via a call to unalias/1.
287 This is also the default behaviour if no options are passed
288 or if alias/0 is called.
289
290 reply:
291 The alias will be automatically deactivated when a reply
292 message sent via the alias is received. The alias can also
293 still be deactivated via a call to unalias/1.
294
295 Example:
296
297 server() ->
298 receive
299 {request, AliasReqId, Request} ->
300 Result = perform_request(Request),
301 AliasReqId ! {reply, AliasReqId, Result}
302 end,
303 server().
304
305 client(ServerPid, Request) ->
306 AliasReqId = alias([reply]),
307 ServerPid ! {request, AliasReqId, Request},
308 %% Alias will be automatically deactivated if we receive a reply
309 %% since we used the 'reply' option...
310 receive
311 {reply, AliasReqId, Result} -> Result
312 after 5000 ->
313 unalias(AliasReqId),
314 %% Flush message queue in case the reply arrived
315 %% just before the alias was deactivated...
316 receive {reply, AliasReqId, Result} -> Result
317 after 0 -> exit(timeout)
318 end
319 end.
320
321
322 Note that both the server and the client in this example must be
323 executing on at least OTP 24 systems in order for this to work.
324
325 For more information on process aliases see the Process Aliases
326 section of the Erlang Reference Manual .
327
328 erlang:append_element(Tuple1, Term) -> Tuple2
329
330 Types:
331
332 Tuple1 = Tuple2 = tuple()
333 Term = term()
334
335 Returns a new tuple that has one element more than Tuple1, and
336 contains the elements in Tuple1 followed by Term as the last el‐
337 ement. Semantically equivalent to list_to_tuple(tu‐
338 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
339
340 > erlang:append_element({one, two}, three).
341 {one,two,three}
342
343 apply(Fun, Args) -> term()
344
345 Types:
346
347 Fun = function()
348 Args = [term()]
349
350 Calls a fun, passing the elements in Args as arguments.
351
352 If the number of elements in the arguments are known at compile
353 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
354
355 Warning:
356 Earlier, Fun could also be specified as {Module, Function},
357 equivalent to apply(Module, Function, Args). This use is depre‐
358 cated and will stop working in a future release.
359
360
361 apply(Module, Function, Args) -> term()
362
363 Types:
364
365 Module = module()
366 Function = atom()
367 Args = [term()]
368
369 Returns the result of applying Function in Module to Args. The
370 applied function must be exported from Module. The arity of the
371 function is the length of Args. Example:
372
373 > apply(lists, reverse, [[a, b, c]]).
374 [c,b,a]
375 > apply(erlang, atom_to_list, ['Erlang']).
376 "Erlang"
377
378 If the number of arguments are known at compile time, the call
379 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
380
381 Failure: error_handler:undefined_function/3 is called if the ap‐
382 plied function is not exported. The error handler can be rede‐
383 fined (see process_flag/2). If error_handler is undefined, or if
384 the user has redefined the default error_handler so the replace‐
385 ment module is undefined, an error with reason undef is gener‐
386 ated.
387
388 atom_to_binary(Atom) -> binary()
389
390 Types:
391
392 Atom = atom()
393
394 The same as atom_to_binary(Atom, utf8).
395
396 atom_to_binary(Atom, Encoding) -> binary()
397
398 Types:
399
400 Atom = atom()
401 Encoding = latin1 | unicode | utf8
402
403 Returns a binary corresponding to the text representation of
404 Atom. If Encoding is latin1, one byte exists for each character
405 in the text representation. If Encoding is utf8 or unicode, the
406 characters are encoded using UTF-8 where characters may require
407 multiple bytes.
408
409 Note:
410 As from Erlang/OTP 20, atoms can contain any Unicode character
411 and atom_to_binary(Atom, latin1) may fail if the text represen‐
412 tation for Atom contains a Unicode character > 255.
413
414
415 Example:
416
417 > atom_to_binary('Erlang', latin1).
418 <<"Erlang">>
419
420 atom_to_list(Atom) -> string()
421
422 Types:
423
424 Atom = atom()
425
426 Returns a list of unicode code points corresponding to the text
427 representation of Atom, for example:
428
429 > atom_to_list('Erlang').
430 "Erlang"
431
432 > atom_to_list('你好').
433 [20320,22909]
434
435 See unicode(3) for how to convert the resulting list to differ‐
436 ent formats.
437
438 binary_part(Subject, PosLen) -> binary()
439
440 Types:
441
442 Subject = binary()
443 PosLen = {Start :: integer() >= 0, Length :: integer()}
444
445 Extracts the part of the binary described by PosLen.
446
447 Negative length can be used to extract bytes at the end of a bi‐
448 nary, for example:
449
450 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
451 2> binary_part(Bin,{byte_size(Bin), -5}).
452 <<6,7,8,9,10>>
453
454 Failure: badarg if PosLen in any way references outside the bi‐
455 nary.
456
457 Start is zero-based, that is:
458
459 1> Bin = <<1,2,3>>
460 2> binary_part(Bin,{0,2}).
461 <<1,2>>
462
463 For details about the PosLen semantics, see binary(3).
464
465 Allowed in guard tests.
466
467 binary_part(Subject, Start, Length) -> binary()
468
469 Types:
470
471 Subject = binary()
472 Start = integer() >= 0
473 Length = integer()
474
475 The same as binary_part(Subject, {Start, Length}).
476
477 Allowed in guard tests.
478
479 binary_to_atom(Binary) -> atom()
480
481 Types:
482
483 Binary = binary()
484
485 The same as binary_to_atom(Binary, utf8).
486
487 binary_to_atom(Binary, Encoding) -> atom()
488
489 Types:
490
491 Binary = binary()
492 Encoding = latin1 | unicode | utf8
493
494 Returns the atom whose text representation is Binary. If Encod‐
495 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
496 quences.
497
498 Note:
499 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
500 of encoding any Unicode character. Earlier versions would fail
501 if the binary contained Unicode characters > 255. For more in‐
502 formation about Unicode support in atoms, see the note on UTF-8
503 encoded atoms in section "External Term Format" in the User's
504 Guide.
505
506
507 Note:
508 The number of characters that are permitted in an atom name is
509 limited. The default limits can be found in the efficiency
510 guide (section Advanced).
511
512
513 Note:
514 There is configurable limit on how many atoms that can exist and
515 atoms are not garbage collected. Therefore, it is recommended to
516 consider whether binary_to_existing_atom/2 is a better option
517 than binary_to_atom/2. The default limits can be found in effi‐
518 ciency guide (section Advanced).
519
520
521 Examples:
522
523 > binary_to_atom(<<"Erlang">>, latin1).
524
525 > binary_to_atom(<<1024/utf8>>, utf8).
526
527 binary_to_existing_atom(Binary) -> atom()
528
529 Types:
530
531 Binary = binary()
532
533 The same as binary_to_existing_atom (Binary, utf8).
534
535 binary_to_existing_atom(Binary, Encoding) -> atom()
536
537 Types:
538
539 Binary = binary()
540 Encoding = latin1 | unicode | utf8
541
542 As binary_to_atom/2, but the atom must exist.
543
544 The Erlang system has a configurable limit for the total number
545 of atoms that can exist, and atoms are not garbage collected.
546 Therefore, it is not safe to create many atoms from binaries
547 that come from an untrusted source (for example, a file fetched
548 from the Internet), for example, using binary_to_atom/2. This
549 function is thus the appropriate option when the input binary
550 comes from an untrusted source.
551
552 An atom exists in an Erlang system when included in a loaded Er‐
553 lang module or when created programmatically (for example, by
554 binary_to_atom/2). See the next note for an example of when an
555 atom exists in the source code for an Erlang module but not in
556 the compiled version of the same module.
557
558 Failure: badarg if the atom does not exist.
559
560 Note:
561 Note that the compiler may optimize away atoms. For example, the
562 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
563 that expression is the only mention of the atom some_atom in the
564 containing module, the atom will not be created when the module
565 is loaded, and a subsequent call to binary_to_exist‐
566 ing_atom(<<"some_atom">>, utf8) will fail.
567
568
569 Note:
570 The number of characters that are permitted in an atom name is
571 limited. The default limits can be found in the efficiency
572 guide (section Advanced).
573
574
575 binary_to_float(Binary) -> float()
576
577 Types:
578
579 Binary = binary()
580
581 Returns the float whose text representation is Binary, for exam‐
582 ple:
583
584 > binary_to_float(<<"2.2017764e+0">>).
585 2.2017764
586
587 The float string format is the same as the format for Erlang
588 float literals except for that underscores are not permitted.
589
590 Failure: badarg if Binary contains a bad representation of a
591 float.
592
593 binary_to_integer(Binary) -> integer()
594
595 Types:
596
597 Binary = binary()
598
599 Returns an integer whose text representation is Binary, for ex‐
600 ample:
601
602 > binary_to_integer(<<"123">>).
603 123
604
605 binary_to_integer/1 accepts the same string formats as
606 list_to_integer/1.
607
608 Failure: badarg if Binary contains a bad representation of an
609 integer.
610
611 binary_to_integer(Binary, Base) -> integer()
612
613 Types:
614
615 Binary = binary()
616 Base = 2..36
617
618 Returns an integer whose text representation in base Base is Bi‐
619 nary, for example:
620
621 > binary_to_integer(<<"3FF">>, 16).
622 1023
623
624 binary_to_integer/2 accepts the same string formats as
625 list_to_integer/2.
626
627 Failure: badarg if Binary contains a bad representation of an
628 integer.
629
630 binary_to_list(Binary) -> [byte()]
631
632 Types:
633
634 Binary = binary()
635
636 Returns a list of integers corresponding to the bytes of Binary.
637
638 binary_to_list(Binary, Start, Stop) -> [byte()]
639
640 Types:
641
642 Binary = binary()
643 Start = Stop = integer() >= 1
644 1..byte_size(Binary)
645
646 As binary_to_list/1, but returns a list of integers correspond‐
647 ing to the bytes from position Start to position Stop in Binary.
648 The positions in the binary are numbered starting from 1.
649
650 Note:
651 The one-based indexing for binaries used by this function is
652 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
653 instead. All functions in module binary consistently use zero-
654 based indexing.
655
656
657 binary_to_term(Binary) -> term()
658
659 Types:
660
661 Binary = ext_binary()
662
663 Returns an Erlang term that is the result of decoding binary ob‐
664 ject Binary, which must be encoded according to the Erlang ex‐
665 ternal term format.
666
667 > Bin = term_to_binary(hello).
668 <<131,100,0,5,104,101,108,108,111>>
669 > hello = binary_to_term(Bin).
670 hello
671
672
673 Warning:
674 When decoding binaries from untrusted sources, the untrusted
675 source may submit data in a way to create resources, such as
676 atoms and remote references, that cannot be garbage collected
677 and lead to Denial of Service attack. In such cases, consider
678 using binary_to_term/2 with the safe option.
679
680
681 See also term_to_binary/1 and binary_to_term/2.
682
683 binary_to_term(Binary, Opts) -> term() | {term(), Used}
684
685 Types:
686
687 Binary = ext_binary()
688 Opt = safe | used
689 Opts = [Opt]
690 Used = integer() >= 1
691
692 As binary_to_term/1, but takes these options:
693
694 safe:
695 Use this option when receiving binaries from an untrusted
696 source.
697
698 When enabled, it prevents decoding data that can be used to
699 attack the Erlang runtime. In the event of receiving unsafe
700 data, decoding fails with a badarg error.
701
702 This prevents creation of new atoms directly, creation of
703 new atoms indirectly (as they are embedded in certain struc‐
704 tures, such as process identifiers, refs, and funs), and
705 creation of new external function references. None of those
706 resources are garbage collected, so unchecked creation of
707 them can exhaust available memory.
708
709 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
710 ** exception error: bad argument
711 > hello.
712 hello
713 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
714 hello
715
716
717 Warning:
718 The safe option ensures the data is safely processed by the
719 Erlang runtime but it does not guarantee the data is safe to
720 your application. You must always validate data from untrusted
721 sources. If the binary is stored or transits through untrusted
722 sources, you should also consider cryptographically signing
723 it.
724
725
726 used:
727 Changes the return value to {Term, Used} where Used is the
728 number of bytes actually read from Binary.
729
730 > Input = <<131,100,0,5,"hello","world">>.
731 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
732 > {Term, Used} = binary_to_term(Input, [used]).
733 {hello, 9}
734 > split_binary(Input, Used).
735 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
736
737
738 Failure: badarg if safe is specified and unsafe data is decoded.
739
740 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
741 ing_atom/1.
742
743 bit_size(Bitstring) -> integer() >= 0
744
745 Types:
746
747 Bitstring = bitstring()
748
749 Returns an integer that is the size in bits of Bitstring, for
750 example:
751
752 > bit_size(<<433:16,3:3>>).
753 19
754 > bit_size(<<1,2,3>>).
755 24
756
757 Allowed in guard tests.
758
759 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
760
761 Types:
762
763 Bitstring = bitstring()
764
765 Returns a list of integers corresponding to the bytes of Bit‐
766 string. If the number of bits in the binary is not divisible by
767 8, the last element of the list is a bitstring containing the
768 remaining 1-7 bits. Examples:
769
770 > bitstring_to_list(<<433:16>>).
771 [1,177]
772
773 > bitstring_to_list(<<433:16,3:3>>).
774 [1,177,<<3:3>>]
775
776 erlang:bump_reductions(Reductions) -> true
777
778 Types:
779
780 Reductions = integer() >= 1
781
782 This implementation-dependent function increments the reduction
783 counter for the calling process. In the Beam emulator, the re‐
784 duction counter is normally incremented by one for each function
785 and BIF call. A context switch is forced when the counter
786 reaches the maximum number of reductions for a process (4000 re‐
787 ductions in Erlang/OTP 19.2 and later).
788
789 Warning:
790 This BIF can be removed in a future version of the Beam machine
791 without prior warning. It is unlikely to be implemented in other
792 Erlang implementations.
793
794
795 byte_size(Bitstring) -> integer() >= 0
796
797 Types:
798
799 Bitstring = bitstring()
800
801 Returns an integer that is the number of bytes needed to contain
802 Bitstring. That is, if the number of bits in Bitstring is not
803 divisible by 8, the resulting number of bytes is rounded up. Ex‐
804 amples:
805
806 > byte_size(<<433:16,3:3>>).
807 3
808 > byte_size(<<1,2,3>>).
809 3
810
811 Allowed in guard tests.
812
813 erlang:cancel_timer(TimerRef) -> Result
814
815 Types:
816
817 TimerRef = reference()
818 Time = integer() >= 0
819 Result = Time | false
820
821 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
822 Ref, []).
823
824 erlang:cancel_timer(TimerRef, Options) -> Result | ok
825
826 Types:
827
828 TimerRef = reference()
829 Async = Info = boolean()
830 Option = {async, Async} | {info, Info}
831 Options = [Option]
832 Time = integer() >= 0
833 Result = Time | false
834
835 Cancels a timer that has been created by erlang:start_timer or
836 erlang:send_after. TimerRef identifies the timer, and was re‐
837 turned by the BIF that created the timer.
838
839 Options:
840
841 {async, Async}:
842 Asynchronous request for cancellation. Async defaults to
843 false, which causes the cancellation to be performed syn‐
844 chronously. When Async is set to true, the cancel operation
845 is performed asynchronously. That is, cancel_timer() sends
846 an asynchronous request for cancellation to the timer ser‐
847 vice that manages the timer, and then returns ok.
848
849 {info, Info}:
850 Requests information about the Result of the cancellation.
851 Info defaults to true, which means the Result is given. When
852 Info is set to false, no information about the result of the
853 cancellation is given.
854
855 * When Async is false: if Info is true, the Result is re‐
856 turned by erlang:cancel_timer(). otherwise ok is returned.
857
858 * When Async is true: if Info is true, a message on the form
859 {cancel_timer, TimerRef, Result} is sent to the caller of
860 erlang:cancel_timer() when the cancellation operation has
861 been performed, otherwise no message is sent.
862
863 More Options may be added in the future.
864
865 If Result is an integer, it represents the time in milliseconds
866 left until the canceled timer would have expired.
867
868 If Result is false, a timer corresponding to TimerRef could not
869 be found. This can be either because the timer had expired, al‐
870 ready had been canceled, or because TimerRef never corresponded
871 to a timer. Even if the timer had expired, it does not tell you
872 if the time-out message has arrived at its destination yet.
873
874 Note:
875 The timer service that manages the timer can be co-located with
876 another scheduler than the scheduler that the calling process is
877 executing on. If so, communication with the timer service takes
878 much longer time than if it is located locally. If the calling
879 process is in critical path, and can do other things while wait‐
880 ing for the result of this operation, or is not interested in
881 the result of the operation, you want to use option {async,
882 true}. If using option {async, false}, the calling process
883 blocks until the operation has been performed.
884
885
886 See also erlang:send_after/4, erlang:start_timer/4, and er‐
887 lang:read_timer/2.
888
889 ceil(Number) -> integer()
890
891 Types:
892
893 Number = number()
894
895 Returns the smallest integer not less than Number. For example:
896
897 > ceil(5.5).
898 6
899
900 Allowed in guard tests.
901
902 check_old_code(Module) -> boolean()
903
904 Types:
905
906 Module = module()
907
908 Returns true if Module has old code, otherwise false.
909
910 See also code(3).
911
912 check_process_code(Pid, Module) -> CheckResult
913
914 Types:
915
916 Pid = pid()
917 Module = module()
918 CheckResult = boolean()
919
920 The same as check_process_code(Pid, Module, []).
921
922 check_process_code(Pid, Module, OptionList) -> CheckResult | async
923
924 Types:
925
926 Pid = pid()
927 Module = module()
928 RequestId = term()
929 Option = {async, RequestId} | {allow_gc, boolean()}
930 OptionList = [Option]
931 CheckResult = boolean() | aborted
932
933 Checks if the node local process identified by Pid executes old
934 code for Module.
935
936 Options:
937
938 {allow_gc, boolean()}:
939 Determines if garbage collection is allowed when performing
940 the operation. If {allow_gc, false} is passed, and a garbage
941 collection is needed to determine the result of the opera‐
942 tion, the operation is aborted (see information on CheckRe‐
943 sult below). The default is to allow garbage collection,
944 that is, {allow_gc, true}.
945
946 {async, RequestId}:
947 The function check_process_code/3 returns the value async
948 immediately after the request has been sent. When the re‐
949 quest has been processed, the process that called this func‐
950 tion is passed a message on the form {check_process_code,
951 RequestId, CheckResult}.
952
953 If Pid equals self(), and no async option has been passed, the
954 operation is performed at once. Otherwise a request for the op‐
955 eration is sent to the process identified by Pid, and is handled
956 when appropriate. If no async option has been passed, the caller
957 blocks until CheckResult is available and can be returned.
958
959 CheckResult informs about the result of the request as follows:
960
961 true:
962 The process identified by Pid executes old code for Module.
963 That is, the current call of the process executes old code
964 for this module, or the process has references to old code
965 for this module, or the process contains funs that refer‐
966 ences old code for this module.
967
968 false:
969 The process identified by Pid does not execute old code for
970 Module.
971
972 aborted:
973 The operation was aborted, as the process needed to be
974 garbage collected to determine the operation result, and the
975 operation was requested by passing option {allow_gc, false}.
976
977 Note:
978 Up until ERTS version 8.*, the check process code operation
979 checks for all types of references to the old code. That is, di‐
980 rect references (e.g. return addresses on the process stack),
981 indirect references (funs in process context), and references to
982 literals in the code.
983
984 As of ERTS version 9.0, the check process code operation only
985 checks for direct references to the code. Indirect references
986 via funs will be ignored. If such funs exist and are used after
987 a purge of the old code, an exception will be raised upon usage
988 (same as the case when the fun is received by the process after
989 the purge). Literals will be taken care of (copied) at a later
990 stage. This behavior can as of ERTS version 8.1 be enabled when
991 building OTP, and will automatically be enabled if dirty sched‐
992 uler support is enabled.
993
994
995 See also code(3).
996
997 Failures:
998
999 badarg:
1000 If Pid is not a node local process identifier.
1001
1002 badarg:
1003 If Module is not an atom.
1004
1005 badarg:
1006 If OptionList is an invalid list of options.
1007
1008 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
1009
1010 Types:
1011
1012 Time = ConvertedTime = integer()
1013 FromUnit = ToUnit = time_unit()
1014
1015 Converts the Time value of time unit FromUnit to the correspond‐
1016 ing ConvertedTime value of time unit ToUnit. The result is
1017 rounded using the floor function.
1018
1019 Warning:
1020 You can lose accuracy and precision when converting between time
1021 units. To minimize such loss, collect all data at native time
1022 unit and do the conversion on the end result.
1023
1024
1025 erlang:crc32(Data) -> integer() >= 0
1026
1027 Types:
1028
1029 Data = iodata()
1030
1031 Computes and returns the crc32 (IEEE 802.3 style) checksum for
1032 Data.
1033
1034 erlang:crc32(OldCrc, Data) -> integer() >= 0
1035
1036 Types:
1037
1038 OldCrc = integer() >= 0
1039 Data = iodata()
1040
1041 Continues computing the crc32 checksum by combining the previous
1042 checksum, OldCrc, with the checksum of Data.
1043
1044 The following code:
1045
1046 X = erlang:crc32(Data1),
1047 Y = erlang:crc32(X,Data2).
1048
1049 assigns the same value to Y as this:
1050
1051 Y = erlang:crc32([Data1,Data2]).
1052
1053 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
1054 integer() >= 0
1055
1056 Types:
1057
1058 FirstCrc = SecondCrc = SecondSize = integer() >= 0
1059
1060 Combines two previously computed crc32 checksums. This computa‐
1061 tion requires the size of the data object for the second check‐
1062 sum to be known.
1063
1064 The following code:
1065
1066 Y = erlang:crc32(Data1),
1067 Z = erlang:crc32(Y,Data2).
1068
1069 assigns the same value to Z as this:
1070
1071 X = erlang:crc32(Data1),
1072 Y = erlang:crc32(Data2),
1073 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
1074
1075 date() -> Date
1076
1077 Types:
1078
1079 Date = calendar:date()
1080
1081 Returns the current date as {Year, Month, Day}.
1082
1083 The time zone and Daylight Saving Time correction depend on the
1084 underlying OS. The return value is based on the OS System Time.
1085 Example:
1086
1087 > date().
1088 {1995,2,19}
1089
1090 erlang:decode_packet(Type, Bin, Options) ->
1091 {ok, Packet, Rest} |
1092 {more, Length} |
1093 {error, Reason}
1094
1095 Types:
1096
1097 Type =
1098 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
1099 line | http | http_bin | httph | httph_bin
1100 Bin = binary()
1101 Options = [Opt]
1102 Opt =
1103 {packet_size, integer() >= 0} |
1104 {line_length, integer() >= 0}
1105 Packet = binary() | HttpPacket
1106 Rest = binary()
1107 Length = integer() >= 0 | undefined
1108 Reason = term()
1109 HttpPacket =
1110 HttpRequest | HttpResponse | HttpHeader | http_eoh |
1111 HttpError
1112 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
1113 sion}
1114 HttpResponse =
1115 {http_response, HttpVersion, integer(), HttpString}
1116 HttpHeader =
1117 {http_header,
1118 integer(),
1119 HttpField,
1120 UnmodifiedField :: HttpString,
1121 Value :: HttpString}
1122 HttpError = {http_error, HttpString}
1123 HttpMethod =
1124 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
1125 'TRACE' | HttpString
1126 HttpUri =
1127 '*' |
1128 {absoluteURI,
1129 http | https,
1130 Host :: HttpString,
1131 Port :: inet:port_number() | undefined,
1132 Path :: HttpString} |
1133 {scheme, Scheme :: HttpString, HttpString} |
1134 {abs_path, HttpString} |
1135 HttpString
1136 HttpVersion =
1137 {Major :: integer() >= 0, Minor :: integer() >= 0}
1138 HttpField =
1139 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
1140 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
1141 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
1142 |
1143 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
1144 'If-Match' | 'If-None-Match' | 'If-Range' |
1145 'If-Unmodified-Since' | 'Max-Forwards' |
1146 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1147 Agent' |
1148 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1149 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1150 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1151 'Content-Encoding' | 'Content-Language' | 'Content-
1152 Length' |
1153 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1154 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1155 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1156 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1157 'Proxy-Connection' | HttpString
1158 HttpString = string() | binary()
1159
1160 Decodes the binary Bin according to the packet protocol speci‐
1161 fied by Type. Similar to the packet handling done by sockets
1162 with option {packet,Type}.
1163
1164 If an entire packet is contained in Bin, it is returned together
1165 with the remainder of the binary as {ok,Packet,Rest}.
1166
1167 If Bin does not contain the entire packet, {more,Length} is re‐
1168 turned. Length is either the expected total size of the packet,
1169 or undefined if the expected packet size is unknown. de‐
1170 code_packet can then be called again with more data added.
1171
1172 If the packet does not conform to the protocol format, {er‐
1173 ror,Reason} is returned.
1174
1175 Types:
1176
1177 raw | 0:
1178 No packet handling is done. The entire binary is returned
1179 unless it is empty.
1180
1181 1 | 2 | 4:
1182 Packets consist of a header specifying the number of bytes
1183 in the packet, followed by that number of bytes. The length
1184 of the header can be one, two, or four bytes; the order of
1185 the bytes is big-endian. The header is stripped off when the
1186 packet is returned.
1187
1188 line:
1189 A packet is a line-terminated by a delimiter byte, default
1190 is the latin-1 newline character. The delimiter byte is in‐
1191 cluded in the returned packet unless the line was truncated
1192 according to option line_length.
1193
1194 asn1 | cdr | sunrm | fcgi | tpkt:
1195 The header is not stripped off.
1196
1197 The meanings of the packet types are as follows:
1198
1199 asn1 - ASN.1 BER:
1200
1201
1202 sunrm - Sun's RPC encoding:
1203
1204
1205 cdr - CORBA (GIOP 1.1):
1206
1207
1208 fcgi - Fast CGI:
1209
1210
1211 tpkt - TPKT format [RFC1006]:
1212
1213
1214 http | httph | http_bin | httph_bin:
1215 The Hypertext Transfer Protocol. The packets are returned
1216 with the format according to HttpPacket described earlier. A
1217 packet is either a request, a response, a header, or an end
1218 of header mark. Invalid lines are returned as HttpError.
1219
1220 Recognized request methods and header fields are returned as
1221 atoms. Others are returned as strings. Strings of unrecog‐
1222 nized header fields are formatted with only capital letters
1223 first and after hyphen characters, for example, "Sec-Web‐
1224 socket-Key". Header field names are also returned in Unmodi‐
1225 fiedField as strings, without any conversion or formatting.
1226
1227 The protocol type http is only to be used for the first line
1228 when an HttpRequest or an HttpResponse is expected. The fol‐
1229 lowing calls are to use httph to get HttpHeaders until
1230 http_eoh is returned, which marks the end of the headers and
1231 the beginning of any following message body.
1232
1233 The variants http_bin and httph_bin return strings (Http‐
1234 String) as binaries instead of lists.
1235
1236 Options:
1237
1238 {packet_size, integer() >= 0}:
1239 Sets the maximum allowed size of the packet body. If the
1240 packet header indicates that the length of the packet is
1241 longer than the maximum allowed length, the packet is con‐
1242 sidered invalid. Defaults to 0, which means no size limit.
1243
1244 {line_length, integer() >= 0}:
1245 For packet type line, lines longer than the indicated length
1246 are truncated.
1247
1248 Option line_length also applies to http* packet types as an
1249 alias for option packet_size if packet_size itself is not
1250 set. This use is only intended for backward compatibility.
1251
1252 {line_delimiter, 0 =< byte() =< 255}:
1253 For packet type line, sets the delimiting byte. Default is
1254 the latin-1 character $\n.
1255
1256 Examples:
1257
1258 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1259 {ok,<<"abc">>,<<"d">>}
1260 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1261 {more,6}
1262
1263 erlang:delete_element(Index, Tuple1) -> Tuple2
1264
1265 Types:
1266
1267 Index = integer() >= 1
1268 1..tuple_size(Tuple1)
1269 Tuple1 = Tuple2 = tuple()
1270
1271 Returns a new tuple with element at Index removed from tuple Tu‐
1272 ple1, for example:
1273
1274 > erlang:delete_element(2, {one, two, three}).
1275 {one,three}
1276
1277 delete_module(Module) -> true | undefined
1278
1279 Types:
1280
1281 Module = module()
1282
1283 Makes the current code for Module become old code and deletes
1284 all references for this module from the export table. Returns
1285 undefined if the module does not exist, otherwise true.
1286
1287 Warning:
1288 This BIF is intended for the code server (see code(3)) and is
1289 not to be used elsewhere.
1290
1291
1292 Failure: badarg if there already is an old version of Module.
1293
1294 demonitor(MonitorRef) -> true
1295
1296 Types:
1297
1298 MonitorRef = reference()
1299
1300 If MonitorRef is a reference that the calling process obtained
1301 by calling monitor/2, this monitoring is turned off. If the mon‐
1302 itoring is already turned off, nothing happens.
1303
1304 Once demonitor(MonitorRef) has returned, it is guaranteed that
1305 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1306 tor, will be placed in the caller message queue in the future.
1307 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1308 placed in the caller message queue before the call. It is there‐
1309 fore usually advisable to remove such a 'DOWN' message from the
1310 message queue after monitoring has been stopped. demonitor(Moni‐
1311 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1312 this cleanup is wanted.
1313
1314 Note:
1315 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1316 asynchronously, that is, the monitor was active until the "de‐
1317 monitor signal" reached the monitored entity. This had one unde‐
1318 sirable effect. You could never know when you were guaranteed
1319 not to receive a DOWN message because of the monitor.
1320
1321 The current behavior can be viewed as two combined operations:
1322 asynchronously send a "demonitor signal" to the monitored entity
1323 and ignore any future results of the monitor.
1324
1325
1326 Failure: It is an error if MonitorRef refers to a monitoring
1327 started by another process. Not all such cases are cheap to
1328 check. If checking is cheap, the call fails with badarg, for ex‐
1329 ample if MonitorRef is a remote reference.
1330
1331 demonitor(MonitorRef, OptionList) -> boolean()
1332
1333 Types:
1334
1335 MonitorRef = reference()
1336 OptionList = [Option]
1337 Option = flush | info
1338
1339 The returned value is true unless info is part of OptionList.
1340
1341 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1342 Ref).
1343
1344 Options:
1345
1346 flush:
1347 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1348 one, from the caller message queue after monitoring has been
1349 stopped.
1350
1351 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1352 following, but more efficient:
1353
1354 demonitor(MonitorRef),
1355 receive
1356 {_, MonitorRef, _, _, _} ->
1357 true
1358 after 0 ->
1359 true
1360 end
1361
1362 info:
1363 The returned value is one of the following:
1364
1365 true:
1366 The monitor was found and removed. In this case, no 'DOWN'
1367 message corresponding to this monitor has been delivered
1368 and will not be delivered.
1369
1370 false:
1371 The monitor was not found and could not be removed. This
1372 probably because someone already has placed a 'DOWN' mes‐
1373 sage corresponding to this monitor in the caller message
1374 queue.
1375
1376 If option info is combined with option flush, false is re‐
1377 turned if a flush was needed, otherwise true.
1378
1379 Note:
1380 More options can be added in a future release.
1381
1382
1383 Failures:
1384
1385 badarg:
1386 If OptionList is not a list.
1387
1388 badarg:
1389 If Option is an invalid option.
1390
1391 badarg:
1392 The same failure as for demonitor/1.
1393
1394 disconnect_node(Node) -> boolean() | ignored
1395
1396 Types:
1397
1398 Node = node()
1399
1400 Forces the disconnection of a node. This appears to the node
1401 Node as if the local node has crashed. This BIF is mainly used
1402 in the Erlang network authentication protocols.
1403
1404 Returns true if disconnection succeeds, otherwise false. If the
1405 local node is not alive, ignored is returned.
1406
1407 Note:
1408 This function may return before nodedown messages have been de‐
1409 livered.
1410
1411
1412 erlang:display(Term) -> true
1413
1414 Types:
1415
1416 Term = term()
1417
1418 Prints a text representation of Term on the standard output.
1419
1420 Warning:
1421 This BIF is intended for debugging only.
1422
1423
1424 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1425
1426 Types:
1427
1428 Size = integer() >= 0
1429 DHandle = dist_handle()
1430 Data = iovec()
1431
1432 Get distribution channel data from the local node that is to be
1433 passed to the remote node. The distribution channel is identi‐
1434 fied by DHandle. If no data is available, the atom none is re‐
1435 turned. One can request to be informed by a message when more
1436 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1437 tion(DHandle).
1438
1439 The returned value when there are data available depends on the
1440 value of the get_size option configured on the distribution
1441 channel identified by DHandle. For more information see the doc‐
1442 umentation of the get_size option for the er‐
1443 lang:dist_ctrl_set_opt/3 function.
1444
1445 Note:
1446 Only the process registered as distribution controller for the
1447 distribution channel identified by DHandle is allowed to call
1448 this function.
1449
1450
1451 This function is used when implementing an alternative distribu‐
1452 tion carrier using processes as distribution controllers. DHan‐
1453 dle is retrived via the callback f_handshake_complete. More in‐
1454 formation can be found in the documentation of ERTS User's Guide
1455 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1456 bution ➜ Distribution Module.
1457
1458 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1459
1460 Types:
1461
1462 DHandle = dist_handle()
1463 Value = boolean()
1464
1465 Returns the value of the get_size option on the distribution
1466 channel identified by DHandle. For more information see the doc‐
1467 umentation of the get_size option for the er‐
1468 lang:dist_ctrl_set_opt/3 function.
1469
1470 Note:
1471 Only the process registered as distribution controller for the
1472 distribution channel identified by DHandle is allowed to call
1473 this function.
1474
1475
1476 This function is used when implementing an alternative distribu‐
1477 tion carrier using processes as distribution controllers. DHan‐
1478 dle is retrived via the callback f_handshake_complete. More in‐
1479 formation can be found in the documentation of ERTS User's Guide
1480 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1481 bution ➜ Distribution Module.
1482
1483 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1484
1485 Types:
1486
1487 DHandle = dist_handle()
1488
1489 Request notification when more data is available to fetch using
1490 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1491 identified by DHandle. When more data is present, the caller
1492 will be sent the message dist_data. Once a dist_data messages
1493 has been sent, no more dist_data messages will be sent until the
1494 dist_ctrl_get_data_notification/1 function has been called
1495 again.
1496
1497 Note:
1498 Only the process registered as distribution controller for the
1499 distribution channel identified by DHandle is allowed to call
1500 this function.
1501
1502
1503 This function is used when implementing an alternative distribu‐
1504 tion carrier using processes as distribution controllers. DHan‐
1505 dle is retrived via the callback f_handshake_complete. More in‐
1506 formation can be found in the documentation of ERTS User's Guide
1507 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1508 bution ➜ Distribution Module.
1509
1510 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1511
1512 Types:
1513
1514 DHandle = dist_handle()
1515 InputHandler = pid()
1516
1517 Register an alternate input handler process for the distribution
1518 channel identified by DHandle. Once this function has been
1519 called, InputHandler is the only process allowed to call er‐
1520 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1521 fing this distribution channel.
1522
1523 Note:
1524 Only the process registered as distribution controller for the
1525 distribution channel identified by DHandle is allowed to call
1526 this function.
1527
1528
1529 This function is used when implementing an alternative distribu‐
1530 tion carrier using processes as distribution controllers. DHan‐
1531 dle is retrived via the callback f_handshake_complete. More in‐
1532 formation can be found in the documentation of ERTS User's Guide
1533 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1534 bution ➜ Distribution Module.
1535
1536 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1537
1538 Types:
1539
1540 DHandle = dist_handle()
1541 Data = iodata()
1542
1543 Deliver distribution channel data from a remote node to the lo‐
1544 cal node.
1545
1546 Note:
1547 Only the process registered as distribution controller for the
1548 distribution channel identified by DHandle is allowed to call
1549 this function unless an alternate input handler process has been
1550 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1551 putHandler). If an alternate input handler has been registered,
1552 only the registered input handler process is allowed to call
1553 this function.
1554
1555
1556 This function is used when implementing an alternative distribu‐
1557 tion carrier using processes as distribution controllers. DHan‐
1558 dle is retrived via the callback f_handshake_complete. More in‐
1559 formation can be found in the documentation of ERTS User's Guide
1560 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1561 bution ➜ Distribution Module.
1562
1563 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1564 OldValue
1565
1566 Types:
1567
1568 DHandle = dist_handle()
1569 Value = OldValue = boolean()
1570
1571 Sets the value of the get_size option on the distribution chan‐
1572 nel identified by DHandle. This option controls the return value
1573 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1574 equals DHandle used when setting this option. When the get_size
1575 option is:
1576
1577 false:
1578 and there are distribution data available, a call to er‐
1579 lang:dist_ctrl_get_data(DHandle) will just return Data to
1580 pass over the channel. This is the default value of the
1581 get_size option.
1582
1583 true:
1584 and there are distribution data available, a call to er‐
1585 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1586 over the channel as well as the Size of Data in bytes. This
1587 is returned as a tuple on the form {Size, Data}.
1588
1589 All options are set to default when a channel is closed.
1590
1591 Note:
1592 Only the process registered as distribution controller for the
1593 distribution channel identified by DHandle is allowed to call
1594 this function.
1595
1596
1597 This function is used when implementing an alternative distribu‐
1598 tion carrier using processes as distribution controllers. DHan‐
1599 dle is retrived via the callback f_handshake_complete. More in‐
1600 formation can be found in the documentation of ERTS User's Guide
1601 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1602 bution ➜ Distribution Module.
1603
1604 element(N, Tuple) -> term()
1605
1606 Types:
1607
1608 N = integer() >= 1
1609 1..tuple_size(Tuple)
1610 Tuple = tuple()
1611
1612 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1613 ple:
1614
1615 > element(2, {a, b, c}).
1616 b
1617
1618 Allowed in guard tests.
1619
1620 erase() -> [{Key, Val}]
1621
1622 Types:
1623
1624 Key = Val = term()
1625
1626 Returns the process dictionary and deletes it, for example:
1627
1628 > put(key1, {1, 2, 3}),
1629 put(key2, [a, b, c]),
1630 erase().
1631 [{key1,{1,2,3}},{key2,[a,b,c]}]
1632
1633 erase(Key) -> Val | undefined
1634
1635 Types:
1636
1637 Key = Val = term()
1638
1639 Returns the value Val associated with Key and deletes it from
1640 the process dictionary. Returns undefined if no value is associ‐
1641 ated with Key. The average time complexity for the current im‐
1642 plementation of this function is O(1) and the worst case time
1643 complexity is O(N), where N is the number of items in the
1644 process dictionary. Example:
1645
1646 > put(key1, {merry, lambs, are, playing}),
1647 X = erase(key1),
1648 {X, erase(key1)}.
1649 {{merry,lambs,are,playing},undefined}
1650
1651 error(Reason) -> no_return()
1652
1653 Types:
1654
1655 Reason = term()
1656
1657 Raises an exception of class error with the reason Reason. As
1658 evaluating this function causes an exception to be thrown, it
1659 has no return value.
1660
1661 The intent of the exception class error is to signal that an un‐
1662 expected error has happened (for example, a function is called
1663 with a parameter that has an incorrect type). See the guide
1664 about errors and error handling for additional information. Ex‐
1665 ample:
1666
1667 > catch error(foobar).
1668 {'EXIT',{foobar,[{shell,apply_fun,3,
1669 [{file,"shell.erl"},{line,906}]},
1670 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1671 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1672 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1673 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1674 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1675
1676
1677 error(Reason, Args) -> no_return()
1678
1679 Types:
1680
1681 Reason = term()
1682 Args = [term()] | none
1683
1684 Raises an exception of class error with the reason Reason. Args
1685 is expected to be the list of arguments for the current function
1686 or the atom none. If it is a list, it is used to provide the ar‐
1687 guments for the current function in the stack back-trace. If it
1688 is none, the arity of the calling function is used in the stack‐
1689 trace. As evaluating this function causes an exception to be
1690 raised, it has no return value.
1691
1692 The intent of the exception class error is to signal that an un‐
1693 expected error has happened (for example, a function is called
1694 with a parameter that has an incorrect type). See the guide
1695 about errors and error handling for additional information. Ex‐
1696 ample:
1697
1698 test.erl:
1699
1700 -module(test).
1701 -export([example_fun/2]).
1702
1703 example_fun(A1, A2) ->
1704 erlang:error(my_error, [A1, A2]).
1705
1706
1707 Erlang shell:
1708
1709 6> c(test).
1710 {ok,test}
1711 7> test:example_fun(arg1,"this is the second argument").
1712 ** exception error: my_error
1713 in function test:example_fun/2
1714 called as test:example_fun(arg1,"this is the second argument")
1715
1716
1717 error(Reason, Args, Options) -> no_return()
1718
1719 Types:
1720
1721 Reason = term()
1722 Args = [term()] | none
1723 Options = [Option]
1724 Option = {error_info, ErrorInfoMap}
1725 ErrorInfoMap =
1726 #{cause => term(), module => module(), function =>
1727 atom()}
1728
1729 Raises an exception of class error with the reason Reason. Args
1730 is expected to be the list of arguments for the current function
1731 or the atom none. If it is a list, it is used to provide the ar‐
1732 guments for the current function in the stack back-trace. If it
1733 is none, the arity of the calling function is used in the stack‐
1734 trace. As evaluating this function causes an exception to be
1735 raised, it has no return value.
1736
1737 If the error_info option is given, the ErrorInfoMap will be in‐
1738 serted into the stacktrace. The information given in the Error‐
1739 InfoMap is to be used by error formatters such as erl_error to
1740 provide more context around an error.
1741
1742 The default module of the ErrorInfoMap is the module that the
1743 call to error/3 is made. The default function is format_error.
1744 See format_error/2 for more details on how this Module:Func‐
1745 tion/2 is to be used
1746
1747 The intent of the exception class error is to signal that an un‐
1748 expected error has happened (for example, a function is called
1749 with a parameter that has an incorrect type). See the guide
1750 about errors and error handling for additional information.
1751
1752 exit(Reason) -> no_return()
1753
1754 Types:
1755
1756 Reason = term()
1757
1758 Raises an exception of class exit with exit reason Reason. As
1759 evaluating this function causes an exception to be raised, it
1760 has no return value.
1761
1762 The intent of the exception class exit is that the current
1763 process should be stopped (for example when a message telling a
1764 process to stop is received).
1765
1766 This function differ from error/1,2,3 by causing an exception of
1767 a different class and by having a reason that does not include
1768 the list of functions from the call stack.
1769
1770 See the guide about errors and error handling for additional in‐
1771 formation.
1772
1773 Example:
1774
1775 > exit(foobar).
1776 ** exception exit: foobar
1777 > catch exit(foobar).
1778 {'EXIT',foobar}
1779
1780 Note:
1781 If a process calls exit(kill) and does not catch the exception,
1782 it will terminate with exit reason kill and also emit exit sig‐
1783 nals with exit reason kill (not killed) to all linked processes.
1784 Such exit signals with exit reason kill can be trapped by the
1785 linked processes. Note that this means that signals with exit
1786 reason kill behave differently depending on how they are sent
1787 because the signal will be untrappable if a process sends such a
1788 signal to another process with erlang:exit/2.
1789
1790
1791 exit(Pid, Reason) -> true
1792
1793 Types:
1794
1795 Pid = pid() | port()
1796 Reason = term()
1797
1798 Sends an exit signal with exit reason Reason to the process or
1799 port identified by Pid.
1800
1801 The following behavior applies if Reason is any term, except
1802 normal or kill, and P is the process or port identified by Pid:
1803
1804 * If P is not trapping exits, P exits with exit reason Reason.
1805
1806 * If P is trapping exits, the exit signal is transformed into
1807 a message {'EXIT', From, Reason}, where From is the process
1808 identifier of the process that sent the exit signal, and de‐
1809 livered to the message queue of P.
1810
1811 The following behavior applies if Reason is the term normal and
1812 Pid is the identifier of a process P which is not the same as
1813 the process that invoked erlang:exit(Pid, normal) (the behavior
1814 when a process sends a signal with the normal reason to itself
1815 is described in the warning):
1816
1817 * If P is trapping exits, the exit signal is transformed into
1818 a message {'EXIT', From, normal}, where From is the process
1819 identifier of the process that sent the exit signal, and de‐
1820 livered to P's message queue.
1821
1822 * The signal has no effect if P is not trapping exits.
1823
1824 If Reason is the atom kill, that is, if exit(Pid, kill) is
1825 called, an untrappable exit signal is sent to the process that
1826 is identified by Pid, which unconditionally exits with exit rea‐
1827 son killed. The exit reason is changed from kill to killed to
1828 hint to linked processes that the killed process got killed by a
1829 call to exit(Pid, kill).
1830
1831 Note:
1832 The functions erlang:exit/1 and erlang:exit/2 are named simi‐
1833 larly but provide very different functionalities. The er‐
1834 lang:exit/1 function should be used when the intent is to stop
1835 the current process while erlang:exit/2 should be used when the
1836 intent is to send an exit signal to another process. Note also
1837 that erlang:exit/1 raises an exception that can be caught while
1838 erlang:exit/2 does not cause any exception to be raised.
1839
1840
1841 Warning:
1842 The only scenario that has not been covered by the description
1843 above is when a process P sends an exit signal with reason nor‐
1844 mal to itself, that is erlang:exit(self(), normal). The behavior
1845 in this scenario is as follows:
1846
1847 * If P is trapping exits, the exit signal is transformed into
1848 a message {'EXIT', From, normal}, where From is P's process
1849 identifier, and delivered to P's message queue.
1850
1851 * P exits with reason normal if P is not trapping exits.
1852
1853 Note that the behavior described above is different from when a
1854 process sends an exit signal with reason normal to another
1855 process. This is arguably strange but this behavior is kept for
1856 backward compatibility reasons.
1857
1858
1859 erlang:external_size(Term) -> integer() >= 0
1860
1861 Types:
1862
1863 Term = term()
1864
1865 Calculates, without doing the encoding, the maximum byte size
1866 for a term encoded in the Erlang external term format. The fol‐
1867 lowing condition applies always:
1868
1869 > Size1 = byte_size(term_to_binary(Term)),
1870 > Size2 = erlang:external_size(Term),
1871 > true = Size1 =< Size2.
1872 true
1873
1874 This is equivalent to a call to:
1875
1876 erlang:external_size(Term, [])
1877
1878 erlang:external_size(Term, Options) -> integer() >= 0
1879
1880 Types:
1881
1882 Term = term()
1883 Options = [{minor_version, Version :: integer() >= 0}]
1884
1885 Calculates, without doing the encoding, the maximum byte size
1886 for a term encoded in the Erlang external term format. The fol‐
1887 lowing condition applies always:
1888
1889 > Size1 = byte_size(term_to_binary(Term, Options)),
1890 > Size2 = erlang:external_size(Term, Options),
1891 > true = Size1 =< Size2.
1892 true
1893
1894 Option {minor_version, Version} specifies how floats are en‐
1895 coded. For a detailed description, see term_to_binary/2.
1896
1897 float(Number) -> float()
1898
1899 Types:
1900
1901 Number = number()
1902
1903 Returns a float by converting Number to a float, for example:
1904
1905 > float(55).
1906 55.0
1907
1908 Allowed in guard tests.
1909
1910 Note:
1911 If used on the top level in a guard, it tests whether the argu‐
1912 ment is a floating point number; for clarity, use is_float/1 in‐
1913 stead.
1914
1915 When float/1 is used in an expression in a guard, such as
1916 'float(A) == 4.0', it converts a number as described earlier.
1917
1918
1919 float_to_binary(Float) -> binary()
1920
1921 Types:
1922
1923 Float = float()
1924
1925 The same as float_to_binary(Float,[{scientific,20}]).
1926
1927 float_to_binary(Float, Options) -> binary()
1928
1929 Types:
1930
1931 Float = float()
1932 Options = [Option]
1933 Option =
1934 {decimals, Decimals :: 0..253} |
1935 {scientific, Decimals :: 0..249} |
1936 compact
1937
1938 Returns a binary corresponding to the text representation of
1939 Float using fixed decimal point formatting. Options behaves in
1940 the same way as float_to_list/2. Examples:
1941
1942 > float_to_binary(7.12, [{decimals, 4}]).
1943 <<"7.1200">>
1944 > float_to_binary(7.12, [{decimals, 4}, compact]).
1945 <<"7.12">>
1946 > float_to_binary(7.12, [{scientific, 3}]).
1947 <<"7.120e+00">>
1948
1949 float_to_list(Float) -> string()
1950
1951 Types:
1952
1953 Float = float()
1954
1955 The same as float_to_list(Float,[{scientific,20}]).
1956
1957 float_to_list(Float, Options) -> string()
1958
1959 Types:
1960
1961 Float = float()
1962 Options = [Option]
1963 Option =
1964 {decimals, Decimals :: 0..253} |
1965 {scientific, Decimals :: 0..249} |
1966 compact
1967
1968 Returns a string corresponding to the text representation of
1969 Float using fixed decimal point formatting.
1970
1971 Available options:
1972
1973 * If option decimals is specified, the returned value contains
1974 at most Decimals number of digits past the decimal point. If
1975 the number does not fit in the internal static buffer of 256
1976 bytes, the function throws badarg.
1977
1978 * If option compact is specified, the trailing zeros at the
1979 end of the list are truncated. This option is only meaning‐
1980 ful together with option decimals.
1981
1982 * If option scientific is specified, the float is formatted
1983 using scientific notation with Decimals digits of precision.
1984
1985 * If Options is [], the function behaves as float_to_list/1.
1986
1987 Examples:
1988
1989 > float_to_list(7.12, [{decimals, 4}]).
1990 "7.1200"
1991 > float_to_list(7.12, [{decimals, 4}, compact]).
1992 "7.12"
1993 > float_to_list(7.12, [{scientific, 3}]).
1994 "7.120e+00"
1995 > float_to_list(0.1+0.2)
1996 "3.00000000000000044409e-01"
1997
1998
1999 In the last example, float_to_list(0.1+0.2) evaluates to
2000 "3.00000000000000044409e-01". The reason for this is explained
2001 in Representation of Floating Point Numbers.
2002
2003 floor(Number) -> integer()
2004
2005 Types:
2006
2007 Number = number()
2008
2009 Returns the largest integer not greater than Number. For exam‐
2010 ple:
2011
2012 > floor(-10.5).
2013 -11
2014
2015 Allowed in guard tests.
2016
2017 erlang:fun_info(Fun) -> [{Item, Info}]
2018
2019 Types:
2020
2021 Fun = function()
2022 Item =
2023 arity | env | index | name | module | new_index |
2024 new_uniq |
2025 pid | type | uniq
2026 Info = term()
2027
2028 Returns a list with information about the fun Fun. Each list el‐
2029 ement is a tuple. The order of the tuples is undefined, and more
2030 tuples can be added in a future release.
2031
2032 Warning:
2033 This BIF is mainly intended for debugging, but it can sometimes
2034 be useful in library functions that need to verify, for example,
2035 the arity of a fun.
2036
2037
2038 Two types of funs have slightly different semantics:
2039
2040 * A fun created by fun M:F/A is called an external fun. Call‐
2041 ing it will always call the function F with arity A in the
2042 latest code for module M. Notice that module M does not even
2043 need to be loaded when the fun fun M:F/A is created.
2044
2045 * All other funs are called local. When a local fun is called,
2046 the same version of the code that created the fun is called
2047 (even if a newer version of the module has been loaded).
2048
2049 The following elements are always present in the list for both
2050 local and external funs:
2051
2052 {type, Type}:
2053 Type is local or external.
2054
2055 {module, Module}:
2056 Module (an atom) is the module name.
2057
2058 If Fun is a local fun, Module is the module in which the fun
2059 is defined.
2060
2061 If Fun is an external fun, Module is the module that the fun
2062 refers to.
2063
2064 {name, Name}:
2065 Name (an atom) is a function name.
2066
2067 If Fun is a local fun, Name is the name of the local func‐
2068 tion that implements the fun. (This name was generated by
2069 the compiler, and is only of informational use. As it is a
2070 local function, it cannot be called directly.) If no code is
2071 currently loaded for the fun, [] is returned instead of an
2072 atom.
2073
2074 If Fun is an external fun, Name is the name of the exported
2075 function that the fun refers to.
2076
2077 {arity, Arity}:
2078 Arity is the number of arguments that the fun is to be
2079 called with.
2080
2081 {env, Env}:
2082 Env (a list) is the environment or free variables for the
2083 fun. For external funs, the returned list is always empty.
2084
2085 The following elements are only present in the list if Fun is
2086 local:
2087
2088 {pid, Pid}:
2089 Pid is the process identifier of the process that originally
2090 created the fun.
2091
2092 It might point to the init process if the Fun was statically
2093 allocated when module was loaded (this optimisation is per‐
2094 formed for local functions that do not capture the environ‐
2095 ment).
2096
2097 {index, Index}:
2098 Index (an integer) is an index into the module fun table.
2099
2100 {new_index, Index}:
2101 Index (an integer) is an index into the module fun table.
2102
2103 {new_uniq, Uniq}:
2104 Uniq (a binary) is a unique value for this fun. It is calcu‐
2105 lated from the compiled code for the entire module.
2106
2107 {uniq, Uniq}:
2108 Uniq (an integer) is a unique value for this fun. As from
2109 Erlang/OTP R15, this integer is calculated from the compiled
2110 code for the entire module. Before Erlang/OTP R15, this in‐
2111 teger was based on only the body of the fun.
2112
2113 erlang:fun_info(Fun, Item) -> {Item, Info}
2114
2115 Types:
2116
2117 Fun = function()
2118 Item = fun_info_item()
2119 Info = term()
2120 fun_info_item() =
2121 arity | env | index | name | module | new_index | new_uniq |
2122 pid | type | uniq
2123
2124 Returns information about Fun as specified by Item, in the form
2125 {Item,Info}.
2126
2127 For any fun, Item can be any of the atoms module, name, arity,
2128 env, or type.
2129
2130 For a local fun, Item can also be any of the atoms index,
2131 new_index, new_uniq, uniq, and pid. For an external fun, the
2132 value of any of these items is always the atom undefined.
2133
2134 See erlang:fun_info/1.
2135
2136 erlang:fun_to_list(Fun) -> String :: string()
2137
2138 Types:
2139
2140 Fun = function()
2141
2142 Returns String that represents the code that created Fun.
2143
2144 String has the following form, if Fun was created by a fun ex‐
2145 pression of the form fun ModuleName:FuncName/Arity:
2146
2147 "fun ModuleName:FuncName/Arity"
2148
2149 The form of String when Fun is created from other types of fun
2150 expressions differs depending on if the fun expression was exe‐
2151 cuted while executing compiled code or if the fun expression was
2152 executed while executing uncompiled code (uncompiled escripts,
2153 the Erlang shell, and other code executed by the erl_eval mod‐
2154 ule):
2155
2156 compiled code:
2157 "#Fun<M.I.U>", where M, I and U correspond to the values
2158 named module, index and uniq in the result of er‐
2159 lang:fun_info(Fun).
2160
2161 uncompiled code:
2162 All funs created from fun expressions in uncompiled code
2163 with the same arity are mapped to the same list by
2164 fun_to_list/1.
2165
2166 Note:
2167 Generally, one can not use fun_to_list/1 to check if two funs
2168 are equal as fun_to_list/1 does not take the fun's environment
2169 into account. See erlang:fun_info/1 for how to get the environ‐
2170 ment of a fun.
2171
2172
2173 Note:
2174 The output of fun_to_list/1 can differ between Erlang implemen‐
2175 tations and may change in future versions.
2176
2177
2178 Examples:
2179
2180 -module(test).
2181 -export([add/1, add2/0, fun_tuple/0]).
2182 add(A) -> fun(B) -> A + B end.
2183 add2() -> fun add/1.
2184 fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
2185
2186
2187 > {fun test:add/1, test:add2()}.
2188 {fun test:add/1,#Fun<test.1.107738983>}
2189
2190
2191 Explanation: fun test:add/1 is upgradable but test:add2() is not
2192 upgradable.
2193
2194 > {test:add(1), test:add(42)}.
2195 {#Fun<test.0.107738983>,#Fun<test.0.107738983>}
2196
2197
2198 Explanation: test:add(1) and test:add(42) has the same string
2199 representation as the environment is not taken into account.
2200
2201 >test:fun_tuple().
2202 {#Fun<test.2.107738983>,#Fun<test.3.107738983>}
2203
2204
2205 Explanation: The string representations differ because the funs
2206 come from different fun experssions.
2207
2208 > {fun() -> 1 end, fun() -> 1 end}. >
2209 {#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
2210
2211
2212 Explanation: All funs created from fun expressions of this form
2213 in uncompiled code with the same arity are mapped to the same
2214 list by fun_to_list/1.
2215
2216 erlang:function_exported(Module, Function, Arity) -> boolean()
2217
2218 Types:
2219
2220 Module = module()
2221 Function = atom()
2222 Arity = arity()
2223
2224 Returns true if the module Module is current and contains an ex‐
2225 ported function Function/Arity, or if there is a BIF (a built-in
2226 function implemented in C) with the specified name, otherwise
2227 returns false.
2228
2229 garbage_collect() -> true
2230
2231 Forces an immediate garbage collection of the executing process.
2232 The function is not to be used unless it has been noticed (or
2233 there are good reasons to suspect) that the spontaneous garbage
2234 collection will occur too late or not at all.
2235
2236 Warning:
2237 Improper use can seriously degrade system performance.
2238
2239
2240 garbage_collect(Pid) -> GCResult
2241
2242 Types:
2243
2244 Pid = pid()
2245 GCResult = boolean()
2246
2247 The same as garbage_collect(Pid, []).
2248
2249 garbage_collect(Pid, OptionList) -> GCResult | async
2250
2251 Types:
2252
2253 Pid = pid()
2254 RequestId = term()
2255 Option = {async, RequestId} | {type, major | minor}
2256 OptionList = [Option]
2257 GCResult = boolean()
2258
2259 Garbage collects the node local process identified by Pid.
2260
2261 Option:
2262
2263 {async, RequestId}:
2264 The function garbage_collect/2 returns the value async imme‐
2265 diately after the request has been sent. When the request
2266 has been processed, the process that called this function is
2267 passed a message on the form {garbage_collect, RequestId,
2268 GCResult}.
2269
2270 {type, 'major' | 'minor'}:
2271 Triggers garbage collection of requested type. Default value
2272 is 'major', which would trigger a fullsweep GC. The option
2273 'minor' is considered a hint and may lead to either minor or
2274 major GC run.
2275
2276 If Pid equals self(), and no async option has been passed, the
2277 garbage collection is performed at once, that is, the same as
2278 calling garbage_collect/0. Otherwise a request for garbage col‐
2279 lection is sent to the process identified by Pid, and will be
2280 handled when appropriate. If no async option has been passed,
2281 the caller blocks until GCResult is available and can be re‐
2282 turned.
2283
2284 GCResult informs about the result of the garbage collection re‐
2285 quest as follows:
2286
2287 true:
2288 The process identified by Pid has been garbage collected.
2289
2290 false:
2291 No garbage collection was performed, as the process identi‐
2292 fied by Pid terminated before the request could be satis‐
2293 fied.
2294
2295 Notice that the same caveats apply as for garbage_collect/0.
2296
2297 Failures:
2298
2299 badarg:
2300 If Pid is not a node local process identifier.
2301
2302 badarg:
2303 If OptionList is an invalid list of options.
2304
2305 get() -> [{Key, Val}]
2306
2307 Types:
2308
2309 Key = Val = term()
2310
2311 Returns the process dictionary as a list of {Key, Val} tuples.
2312 The items in the returned list can be in any order. Example:
2313
2314 > put(key1, merry),
2315 put(key2, lambs),
2316 put(key3, {are, playing}),
2317 get().
2318 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
2319
2320 get(Key) -> Val | undefined
2321
2322 Types:
2323
2324 Key = Val = term()
2325
2326 Returns the value Val associated with Key in the process dictio‐
2327 nary, or undefined if Key does not exist. The expected time com‐
2328 plexity for the current implementation of this function is O(1)
2329 and the worst case time complexity is O(N), where N is the num‐
2330 ber of items in the process dictionary. Example:
2331
2332 > put(key1, merry),
2333 put(key2, lambs),
2334 put({any, [valid, term]}, {are, playing}),
2335 get({any, [valid, term]}).
2336 {are,playing}
2337
2338 erlang:get_cookie() -> Cookie | nocookie
2339
2340 Types:
2341
2342 Cookie = atom()
2343
2344 Returns the magic cookie of the local node if the node is alive,
2345 otherwise the atom nocookie.
2346
2347 erlang:get_cookie(Node) -> Cookie | nocookie
2348
2349 Types:
2350
2351 Node = node()
2352 Cookie = atom()
2353
2354 Returns the magic cookie for node Node if the local node is
2355 alive, otherwise the atom nocookie.
2356
2357 get_keys() -> [Key]
2358
2359 Types:
2360
2361 Key = term()
2362
2363 Returns a list of all keys present in the process dictionary.
2364 The items in the returned list can be in any order. Example:
2365
2366 > put(dog, {animal,1}),
2367 put(cow, {animal,2}),
2368 put(lamb, {animal,3}),
2369 get_keys().
2370 [dog,cow,lamb]
2371
2372 get_keys(Val) -> [Key]
2373
2374 Types:
2375
2376 Val = Key = term()
2377
2378 Returns a list of keys that are associated with the value Val in
2379 the process dictionary. The items in the returned list can be in
2380 any order. Example:
2381
2382 > put(mary, {1, 2}),
2383 put(had, {1, 2}),
2384 put(a, {1, 2}),
2385 put(little, {1, 2}),
2386 put(dog, {1, 3}),
2387 put(lamb, {1, 2}),
2388 get_keys({1, 2}).
2389 [mary,had,a,little,lamb]
2390
2391 group_leader() -> pid()
2392
2393 Returns the process identifier of the group leader for the
2394 process evaluating the function.
2395
2396 Every process is a member of some process group and all groups
2397 have a group leader. All I/O from the group is channeled to the
2398 group leader. When a new process is spawned, it gets the same
2399 group leader as the spawning process. Initially, at system
2400 startup, init is both its own group leader and the group leader
2401 of all processes.
2402
2403 group_leader(GroupLeader, Pid) -> true
2404
2405 Types:
2406
2407 GroupLeader = Pid = pid()
2408
2409 Sets the group leader of Pid to GroupLeader. Typically, this is
2410 used when a process started from a certain shell is to have an‐
2411 other group leader than init.
2412
2413 The group leader should be rarely changed in applications with a
2414 supervision tree, because OTP assumes the group leader of their
2415 processes is their application master.
2416
2417 Setting the group leader follows the signal ordering guarentees
2418 described in the Processes Chapter in the Erlang Reference Man‐
2419 ual .
2420
2421 See also group_leader/0 and OTP design principles related to
2422 starting and stopping applications.
2423
2424 halt() -> no_return()
2425
2426 The same as halt(0, []). Example:
2427
2428 > halt().
2429 os_prompt%
2430
2431 halt(Status) -> no_return()
2432
2433 Types:
2434
2435 Status = integer() >= 0 | abort | string()
2436
2437 The same as halt(Status, []). Example:
2438
2439 > halt(17).
2440 os_prompt% echo $?
2441 17
2442 os_prompt%
2443
2444 halt(Status, Options) -> no_return()
2445
2446 Types:
2447
2448 Status = integer() >= 0 | abort | string()
2449 Options = [Option]
2450 Option = {flush, boolean()}
2451
2452 Status must be a non-negative integer, a string, or the atom
2453 abort. Halts the Erlang runtime system. Has no return value. De‐
2454 pending on Status, the following occurs:
2455
2456 integer():
2457 The runtime system exits with integer value Status as status
2458 code to the calling environment (OS).
2459
2460 Note:
2461 On many platforms, the OS supports only status codes 0-255. A
2462 too large status code is truncated by clearing the high bits.
2463
2464
2465 string():
2466 An Erlang crash dump is produced with Status as slogan. Then
2467 the runtime system exits with status code 1. The string will
2468 be truncated if longer than 200 characters.
2469
2470 Note:
2471 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2472 was accepted in the string. Now any unicode string is valid.
2473
2474
2475 abort:
2476 The runtime system aborts producing a core dump, if that is
2477 enabled in the OS.
2478
2479 For integer Status, the Erlang runtime system closes all ports
2480 and allows async threads to finish their operations before exit‐
2481 ing. To exit without such flushing, use Option as {flush,false}.
2482
2483 For statuses string() and abort, option flush is ignored and
2484 flushing is not done.
2485
2486 hd(List) -> term()
2487
2488 Types:
2489
2490 List = [term(), ...]
2491
2492 Returns the head of List, that is, the first element, for exam‐
2493 ple:
2494
2495 > hd([1,2,3,4,5]).
2496 1
2497
2498 Allowed in guard tests.
2499
2500 Failure: badarg if List is the empty list [].
2501
2502 erlang:hibernate(Module, Function, Args) -> no_return()
2503
2504 Types:
2505
2506 Module = module()
2507 Function = atom()
2508 Args = [term()]
2509
2510 Puts the calling process into a wait state where its memory al‐
2511 location has been reduced as much as possible. This is useful if
2512 the process does not expect to receive any messages soon.
2513
2514 The process is awaken when a message is sent to it, and control
2515 resumes in Module:Function with the arguments specified by Args
2516 with the call stack emptied, meaning that the process terminates
2517 when that function returns. Thus erlang:hibernate/3 never re‐
2518 turns to its caller. The resume function Module:Function/Arity
2519 must be exported (Arity =:= length(Args)).
2520
2521 If the process has any message in its message queue, the process
2522 is awakened immediately in the same way as described earlier.
2523
2524 In more technical terms, erlang:hibernate/3 discards the call
2525 stack for the process, and then garbage collects the process.
2526 After this, all live data is in one continuous heap. The heap is
2527 then shrunken to the exact same size as the live data that it
2528 holds (even if that size is less than the minimum heap size for
2529 the process).
2530
2531 If the size of the live data in the process is less than the
2532 minimum heap size, the first garbage collection occurring after
2533 the process is awakened ensures that the heap size is changed to
2534 a size not smaller than the minimum heap size.
2535
2536 Notice that emptying the call stack means that any surrounding
2537 catch is removed and must be re-inserted after hibernation. One
2538 effect of this is that processes started using proc_lib (also
2539 indirectly, such as gen_server processes), are to use
2540 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2541 dler continues to work when the process wakes up.
2542
2543 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2544
2545 Types:
2546
2547 Index = integer() >= 1
2548 1..tuple_size(Tuple1) + 1
2549 Tuple1 = Tuple2 = tuple()
2550 Term = term()
2551
2552 Returns a new tuple with element Term inserted at position Index
2553 in tuple Tuple1. All elements from position Index and upwards
2554 are pushed one step higher in the new tuple Tuple2. Example:
2555
2556 > erlang:insert_element(2, {one, two, three}, new).
2557 {one,new,two,three}
2558
2559 integer_to_binary(Integer) -> binary()
2560
2561 Types:
2562
2563 Integer = integer()
2564
2565 Returns a binary corresponding to the text representation of In‐
2566 teger, for example:
2567
2568 > integer_to_binary(77).
2569 <<"77">>
2570
2571 integer_to_binary(Integer, Base) -> binary()
2572
2573 Types:
2574
2575 Integer = integer()
2576 Base = 2..36
2577
2578 Returns a binary corresponding to the text representation of In‐
2579 teger in base Base, for example:
2580
2581 > integer_to_binary(1023, 16).
2582 <<"3FF">>
2583
2584 integer_to_list(Integer) -> string()
2585
2586 Types:
2587
2588 Integer = integer()
2589
2590 Returns a string corresponding to the text representation of In‐
2591 teger, for example:
2592
2593 > integer_to_list(77).
2594 "77"
2595
2596 integer_to_list(Integer, Base) -> string()
2597
2598 Types:
2599
2600 Integer = integer()
2601 Base = 2..36
2602
2603 Returns a string corresponding to the text representation of In‐
2604 teger in base Base, for example:
2605
2606 > integer_to_list(1023, 16).
2607 "3FF"
2608
2609 iolist_size(Item) -> integer() >= 0
2610
2611 Types:
2612
2613 Item = iolist() | binary()
2614
2615 Returns an integer, that is the size in bytes, of the binary
2616 that would be the result of iolist_to_binary(Item), for example:
2617
2618 > iolist_size([1,2|<<3,4>>]).
2619 4
2620
2621 iolist_to_binary(IoListOrBinary) -> binary()
2622
2623 Types:
2624
2625 IoListOrBinary = iolist() | binary()
2626
2627 Returns a binary that is made from the integers and binaries in
2628 IoListOrBinary, for example:
2629
2630 > Bin1 = <<1,2,3>>.
2631 <<1,2,3>>
2632 > Bin2 = <<4,5>>.
2633 <<4,5>>
2634 > Bin3 = <<6>>.
2635 <<6>>
2636 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2637 <<1,2,3,1,2,3,4,5,4,6>>
2638
2639 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2640
2641 Types:
2642
2643 IoListOrBinary = iolist() | binary()
2644
2645 Returns an iovec that is made from the integers and binaries in
2646 IoListOrBinary. This function is useful when you want to flatten
2647 an iolist but you do not need a single binary. This can be use‐
2648 ful for passing the data to nif functions such as enif_in‐
2649 spect_iovec or do more efficient message passing. The advantage
2650 of using this function over iolist_to_binary/1 is that it does
2651 not have to copy off-heap binaries. Example:
2652
2653 > Bin1 = <<1,2,3>>.
2654 <<1,2,3>>
2655 > Bin2 = <<4,5>>.
2656 <<4,5>>
2657 > Bin3 = <<6>>.
2658 <<6>>
2659 %% If you pass small binaries and integers it works as iolist_to_binary
2660 > erlang:iolist_to_iovec([Bin1,1,[2,3,Bin2],4|Bin3]).
2661 [<<1,2,3,1,2,3,4,5,4,6>>]
2662 %% If you pass larger binaries, they are split and returned in a form
2663 %% optimized for calling the C function writev.
2664 > erlang:iolist_to_iovec([<<1>>,<<2:8096>>,<<3:8096>>]).
2665 [<<1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
2666 0,...>>,
2667 <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
2668 ...>>,
2669 <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,...>>]
2670
2671 is_alive() -> boolean()
2672
2673 Returns true if the local node is alive (that is, if the node
2674 can be part of a distributed system), otherwise false. A node is
2675 alive if it is started with:
2676
2677 * "erl -name LONGNAME" or,
2678
2679 * "erl -sname SHORTNAME".
2680
2681 A node can also be alive if it has got a name from a call to
2682 net_kernel:start/1 and has not been stopped by a call to
2683 net_kernel:stop/0.
2684
2685 is_atom(Term) -> boolean()
2686
2687 Types:
2688
2689 Term = term()
2690
2691 Returns true if Term is an atom, otherwise false.
2692
2693 Allowed in guard tests.
2694
2695 is_binary(Term) -> boolean()
2696
2697 Types:
2698
2699 Term = term()
2700
2701 Returns true if Term is a binary, otherwise false.
2702
2703 A binary always contains a complete number of bytes.
2704
2705 Allowed in guard tests.
2706
2707 is_bitstring(Term) -> boolean()
2708
2709 Types:
2710
2711 Term = term()
2712
2713 Returns true if Term is a bitstring (including a binary), other‐
2714 wise false.
2715
2716 Allowed in guard tests.
2717
2718 is_boolean(Term) -> boolean()
2719
2720 Types:
2721
2722 Term = term()
2723
2724 Returns true if Term is the atom true or the atom false (that
2725 is, a boolean). Otherwise returns false.
2726
2727 Allowed in guard tests.
2728
2729 erlang:is_builtin(Module, Function, Arity) -> boolean()
2730
2731 Types:
2732
2733 Module = module()
2734 Function = atom()
2735 Arity = arity()
2736
2737 This BIF is useful for builders of cross-reference tools.
2738
2739 Returns true if Module:Function/Arity is a BIF implemented in C,
2740 otherwise false.
2741
2742 is_float(Term) -> boolean()
2743
2744 Types:
2745
2746 Term = term()
2747
2748 Returns true if Term is a floating point number, otherwise
2749 false.
2750
2751 Allowed in guard tests.
2752
2753 is_function(Term) -> boolean()
2754
2755 Types:
2756
2757 Term = term()
2758
2759 Returns true if Term is a fun, otherwise false.
2760
2761 Allowed in guard tests.
2762
2763 is_function(Term, Arity) -> boolean()
2764
2765 Types:
2766
2767 Term = term()
2768 Arity = arity()
2769
2770 Returns true if Term is a fun that can be applied with Arity
2771 number of arguments, otherwise false.
2772
2773 Allowed in guard tests.
2774
2775 is_integer(Term) -> boolean()
2776
2777 Types:
2778
2779 Term = term()
2780
2781 Returns true if Term is an integer, otherwise false.
2782
2783 Allowed in guard tests.
2784
2785 is_list(Term) -> boolean()
2786
2787 Types:
2788
2789 Term = term()
2790
2791 Returns true if Term is a list with zero or more elements, oth‐
2792 erwise false.
2793
2794 Allowed in guard tests.
2795
2796 is_map(Term) -> boolean()
2797
2798 Types:
2799
2800 Term = term()
2801
2802 Returns true if Term is a map, otherwise false.
2803
2804 Allowed in guard tests.
2805
2806 is_map_key(Key, Map) -> boolean()
2807
2808 Types:
2809
2810 Key = term()
2811 Map = map()
2812
2813 Returns true if map Map contains Key and returns false if it
2814 does not contain the Key.
2815
2816 The call fails with a {badmap,Map} exception if Map is not a
2817 map.
2818
2819 Example:
2820
2821 > Map = #{"42" => value}.
2822 #{"42" => value}
2823 > is_map_key("42",Map).
2824 true
2825 > is_map_key(value,Map).
2826 false
2827
2828 Allowed in guard tests.
2829
2830 is_number(Term) -> boolean()
2831
2832 Types:
2833
2834 Term = term()
2835
2836 Returns true if Term is an integer or a floating point number.
2837 Otherwise returns false.
2838
2839 Allowed in guard tests.
2840
2841 is_pid(Term) -> boolean()
2842
2843 Types:
2844
2845 Term = term()
2846
2847 Returns true if Term is a process identifier, otherwise false.
2848
2849 Allowed in guard tests.
2850
2851 is_port(Term) -> boolean()
2852
2853 Types:
2854
2855 Term = term()
2856
2857 Returns true if Term is a port identifier, otherwise false.
2858
2859 Allowed in guard tests.
2860
2861 is_process_alive(Pid) -> boolean()
2862
2863 Types:
2864
2865 Pid = pid()
2866
2867 Pid must refer to a process at the local node.
2868
2869 Returns true if the process exists and is alive, that is, is not
2870 exiting and has not exited. Otherwise returns false.
2871
2872 If process P1 calls is_process_alive(P2Pid) it is guaranteed
2873 that all signals, sent from P1 to P2 (P2 is the process with
2874 identifier P2Pid) before the call, will be delivered to P2 be‐
2875 fore the aliveness of P2 is checked. This guarantee means that
2876 one can use is_process_alive/1 to let a process P1 wait until a
2877 process P2, which has got an exit signal with reason kill from
2878 P1, is killed. Example:
2879
2880 exit(P2Pid, kill),
2881 % P2 might not be killed
2882 is_process_alive(P2Pid),
2883 % P2 is not alive (the call above always return false)
2884
2885
2886 See the documentation about signals and erlang:exit/2 for more
2887 information about signals and exit singnals.
2888
2889 is_record(Term, RecordTag) -> boolean()
2890
2891 Types:
2892
2893 Term = term()
2894 RecordTag = atom()
2895
2896 Returns true if Term is a tuple and its first element is Record‐
2897 Tag. Otherwise returns false.
2898
2899 Note:
2900 Normally the compiler treats calls to is_record/2 especially. It
2901 emits code to verify that Term is a tuple, that its first ele‐
2902 ment is RecordTag, and that the size is correct. However, if
2903 RecordTag is not a literal atom, the BIF is_record/2 is called
2904 instead and the size of the tuple is not verified.
2905
2906
2907 Allowed in guard tests, if RecordTag is a literal atom.
2908
2909 is_record(Term, RecordTag, Size) -> boolean()
2910
2911 Types:
2912
2913 Term = term()
2914 RecordTag = atom()
2915 Size = integer() >= 0
2916
2917 RecordTag must be an atom.
2918
2919 Returns true if Term is a tuple, its first element is RecordTag,
2920 and its size is Size. Otherwise returns false.
2921
2922 Allowed in guard tests if RecordTag is a literal atom and Size
2923 is a literal integer.
2924
2925 Note:
2926 This BIF is documented for completeness. Usually is_record/2 is
2927 to be used.
2928
2929
2930 is_reference(Term) -> boolean()
2931
2932 Types:
2933
2934 Term = term()
2935
2936 Returns true if Term is a reference, otherwise false.
2937
2938 Allowed in guard tests.
2939
2940 is_tuple(Term) -> boolean()
2941
2942 Types:
2943
2944 Term = term()
2945
2946 Returns true if Term is a tuple, otherwise false.
2947
2948 Allowed in guard tests.
2949
2950 length(List) -> integer() >= 0
2951
2952 Types:
2953
2954 List = [term()]
2955
2956 Returns the length of List, for example:
2957
2958 > length([1,2,3,4,5,6,7,8,9]).
2959 9
2960
2961 Allowed in guard tests.
2962
2963 link(PidOrPort) -> true
2964
2965 Types:
2966
2967 PidOrPort = pid() | port()
2968
2969 Sets up and activates a link between the calling process and an‐
2970 other process or a port identified by PidOrPort. We will from
2971 here on call the identified process or port linkee. If the lin‐
2972 kee is a port, it must reside on the same node as the caller.
2973
2974 If one of the participants of a link terminates, it will send an
2975 exit signal to the other participant. The exit signal will con‐
2976 tain the exit reason of the terminated participant. Other cases
2977 when exit signals are triggered due to a link are when no linkee
2978 exist (noproc exit reason) and when the connection between
2979 linked processes on different nodes is lost or cannot be estab‐
2980 lished (noconnection exit reason).
2981
2982 An existing link can be removed by calling unlink/1. For more
2983 information on links and exit signals due to links, see the Pro‐
2984 cesses chapter in the Erlang Reference Manual :
2985
2986 * Links
2987
2988 * Sending Exit Signals
2989
2990 * Receiving Exit Signals
2991
2992 For historical reasons, link/1 has a strange semi-synchronous
2993 behavior when it is "cheap" to check if the linkee exists or
2994 not, and the caller does not trap exits. If the above is true
2995 and the linkee does not exist, link/1 will raise a noproc error
2996 exception. The expected behavior would instead have been that
2997 link/1 returned true, and the caller later was sent an exit sig‐
2998 nal with noproc exit reason, but this is unfortunately not the
2999 case. The noproc exception is not to be confused with an exit
3000 signal with exit reason noproc. Currently it is "cheap" to check
3001 if the linkee exists when it is supposed to reside on the same
3002 node as the calling process.
3003
3004 The link setup and activation is performed asynchronously. If
3005 the link already exists, or if the caller attempts to create a
3006 link to itself, nothing is done. A detailed description of the
3007 link protocol can be found in the Distribution Protocol chapter
3008 of the ERTS User's Guide .
3009
3010 Failure:
3011
3012 * badarg if PidOrPort does not identify a process or a node
3013 local port.
3014
3015 * noproc linkee does not exist and it is "cheap" to check if
3016 it exists as described above.
3017
3018 list_to_atom(String) -> atom()
3019
3020 Types:
3021
3022 String = string()
3023
3024 Returns the atom whose text representation is String.
3025
3026 As from Erlang/OTP 20, String may contain any Unicode character.
3027 Earlier versions allowed only ISO-latin-1 characters as the im‐
3028 plementation did not allow Unicode characters above 255. For
3029 more information on Unicode support in atoms, see note on UTF-8
3030 encoded atoms in section "External Term Format" in the User's
3031 Guide.
3032
3033 Note:
3034 The number of characters that are permitted in an atom name is
3035 limited. The default limits can be found in the efficiency
3036 guide (section Advanced).
3037
3038
3039 Note:
3040 There is configurable limit on how many atoms that can exist and
3041 atoms are not garbage collected. Therefore, it is recommended to
3042 consider if list_to_existing_atom/1 is a better option than
3043 list_to_atom/1. The default limits can be found in the effi‐
3044 ciency guide (section Advanced).
3045
3046
3047 Example:
3048
3049 > list_to_atom("Erlang").
3050
3051 list_to_binary(IoList) -> binary()
3052
3053 Types:
3054
3055 IoList = iolist()
3056
3057 Returns a binary that is made from the integers and binaries in
3058 IoList, for example:
3059
3060 > Bin1 = <<1,2,3>>.
3061 <<1,2,3>>
3062 > Bin2 = <<4,5>>.
3063 <<4,5>>
3064 > Bin3 = <<6>>.
3065 <<6>>
3066 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
3067 <<1,2,3,1,2,3,4,5,4,6>>
3068
3069 list_to_bitstring(BitstringList) -> bitstring()
3070
3071 Types:
3072
3073 BitstringList = bitstring_list()
3074 bitstring_list() =
3075 maybe_improper_list(byte() | bitstring() | bitstring_list(),
3076 bitstring() | [])
3077
3078 Returns a bitstring that is made from the integers and bit‐
3079 strings in BitstringList. (The last tail in BitstringList is al‐
3080 lowed to be a bitstring.) Example:
3081
3082 > Bin1 = <<1,2,3>>.
3083 <<1,2,3>>
3084 > Bin2 = <<4,5>>.
3085 <<4,5>>
3086 > Bin3 = <<6,7:4>>.
3087 <<6,7:4>>
3088 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
3089 <<1,2,3,1,2,3,4,5,4,6,7:4>>
3090
3091 list_to_existing_atom(String) -> atom()
3092
3093 Types:
3094
3095 String = string()
3096
3097 Returns the atom whose text representation is String, but only
3098 if there already exists such atom. An atom exists if it has been
3099 created by the run-time system by either loading code or creat‐
3100 ing a term in which the atom is part.
3101
3102 Failure: badarg if there does not already exist an atom whose
3103 text representation is String.
3104
3105 Note:
3106 Note that the compiler may optimize away atoms. For example, the
3107 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
3108 that expression is the only mention of the atom some_atom in the
3109 containing module, the atom will not be created when the module
3110 is loaded, and a subsequent call to list_to_exist‐
3111 ing_atom("some_atom") will fail.
3112
3113
3114 list_to_float(String) -> float()
3115
3116 Types:
3117
3118 String = string()
3119
3120 Returns the float whose text representation is String, for exam‐
3121 ple:
3122
3123 > list_to_float("2.2017764e+0").
3124 2.2017764
3125
3126 The float string format is the same as the format for Erlang
3127 float literals except for that underscores are not permitted.
3128
3129 Failure: badarg if String contains a bad representation of a
3130 float.
3131
3132 list_to_integer(String) -> integer()
3133
3134 Types:
3135
3136 String = string()
3137
3138 Returns an integer whose text representation is String, for ex‐
3139 ample:
3140
3141 > list_to_integer("123").
3142 123
3143
3144 > list_to_integer("-123").
3145 -123
3146
3147 > list_to_integer("+123234982304982309482093833234234").
3148 123234982304982309482093833234234
3149
3150 String must contain at least one digit character and can have an
3151 optional prefix consisting of a single "+" or "-" character
3152 (that is, String must match the regular expression
3153 "^[+-]?[0-9]+$").
3154
3155 Failure: badarg if String contains a bad representation of an
3156 integer.
3157
3158 list_to_integer(String, Base) -> integer()
3159
3160 Types:
3161
3162 String = string()
3163 Base = 2..36
3164
3165 Returns an integer whose text representation in base Base is
3166 String, for example:
3167
3168 > list_to_integer("3FF", 16).
3169 1023
3170
3171 > list_to_integer("+3FF", 16).
3172 1023
3173
3174 > list_to_integer("3ff", 16).
3175 1023
3176
3177 > list_to_integer("3fF", 16).
3178 1023
3179
3180 > list_to_integer("-3FF", 16).
3181 -1023
3182
3183 For example, when Base is 16, String must match the regular ex‐
3184 pression "^[+-]?([0-9]|[A-F]|[a-f])+$".
3185
3186 Failure: badarg if String contains a bad representation of an
3187 integer.
3188
3189 list_to_pid(String) -> pid()
3190
3191 Types:
3192
3193 String = string()
3194
3195 Returns a process identifier whose text representation is a
3196 String, for example:
3197
3198 > list_to_pid("<0.4.1>").
3199 <0.4.1>
3200
3201 Failure: badarg if String contains a bad representation of a
3202 process identifier.
3203
3204 Warning:
3205 This BIF is intended for debugging and is not to be used in ap‐
3206 plication programs.
3207
3208
3209 list_to_port(String) -> port()
3210
3211 Types:
3212
3213 String = string()
3214
3215 Returns a port identifier whose text representation is a String,
3216 for example:
3217
3218 > list_to_port("#Port<0.4>").
3219 #Port<0.4>
3220
3221 Failure: badarg if String contains a bad representation of a
3222 port identifier.
3223
3224 Warning:
3225 This BIF is intended for debugging and is not to be used in ap‐
3226 plication programs.
3227
3228
3229 list_to_ref(String) -> reference()
3230
3231 Types:
3232
3233 String = string()
3234
3235 Returns a reference whose text representation is a String, for
3236 example:
3237
3238 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
3239 #Ref<0.4192537678.4073193475.71181>
3240
3241 Failure: badarg if String contains a bad representation of a
3242 reference.
3243
3244 Warning:
3245 This BIF is intended for debugging and is not to be used in ap‐
3246 plication programs.
3247
3248
3249 list_to_tuple(List) -> tuple()
3250
3251 Types:
3252
3253 List = [term()]
3254
3255 Returns a tuple corresponding to List, for example
3256
3257 > list_to_tuple([share, ['Ericsson_B', 163]]).
3258 {share, ['Ericsson_B', 163]}
3259
3260 List can contain any Erlang terms.
3261
3262 load_module(Module, Binary) -> {module, Module} | {error, Reason}
3263
3264 Types:
3265
3266 Module = module()
3267 Binary = binary()
3268 Reason = badfile | not_purged | on_load
3269
3270 If Binary contains the object code for module Module, this BIF
3271 loads that object code. If the code for module Module already
3272 exists, all export references are replaced so they point to the
3273 newly loaded code. The previously loaded code is kept in the
3274 system as old code, as there can still be processes executing
3275 that code.
3276
3277 Returns either {module, Module}, or {error, Reason} if loading
3278 fails. Reason is one of the following:
3279
3280 badfile:
3281 The object code in Binary has an incorrect format or the ob‐
3282 ject code contains code for another module than Module.
3283
3284 not_purged:
3285 Binary contains a module that cannot be loaded because old
3286 code for this module already exists.
3287
3288 on_load:
3289 The code in Binary contains an on_load declaration that must
3290 be executed before Binary can become the current code. Any
3291 previous current code for Module will remain until the
3292 on_load call has finished.
3293
3294 Warning:
3295 This BIF is intended for the code server (see code(3)) and is
3296 not to be used elsewhere.
3297
3298
3299 erlang:load_nif(Path, LoadInfo) -> ok | Error
3300
3301 Types:
3302
3303 Path = string()
3304 LoadInfo = term()
3305 Error = {error, {Reason, Text :: string()}}
3306 Reason =
3307 load_failed | bad_lib | load | reload | upgrade |
3308 old_code
3309
3310 Loads and links a dynamic library containing native implemented
3311 functions (NIFs) for a module. Path is a file path to the share‐
3312 able object/dynamic library file minus the OS-dependent file ex‐
3313 tension (.so for Unix and .dll for Windows). Notice that on most
3314 OSs the library has to have a different name on disc when an up‐
3315 grade of the nif is done. If the name is the same, but the con‐
3316 tents differ, the old library may be loaded instead. For infor‐
3317 mation on how to implement a NIF library, see erl_nif(3).
3318
3319 LoadInfo can be any term. It is passed on to the library as part
3320 of the initialization. A good practice is to include a module
3321 version number to support future code upgrade scenarios.
3322
3323 The call to load_nif/2 must be made directly from the Erlang
3324 code of the module that the NIF library belongs to. It returns
3325 either ok, or {error,{Reason,Text}} if loading fails. Reason is
3326 one of the following atoms while Text is a human readable string
3327 that can give more information about the failure:
3328
3329 load_failed:
3330 The OS failed to load the NIF library.
3331
3332 bad_lib:
3333 The library did not fulfill the requirements as a NIF li‐
3334 brary of the calling module.
3335
3336 load | upgrade:
3337 The corresponding library callback was unsuccessful.
3338
3339 reload:
3340 A NIF library is already loaded for this module instance.
3341 The previously deprecated reload feature was removed in OTP
3342 20.
3343
3344 old_code:
3345 The call to load_nif/2 was made from the old code of a mod‐
3346 ule that has been upgraded; this is not allowed.
3347
3348 erlang:loaded() -> [Module]
3349
3350 Types:
3351
3352 Module = module()
3353
3354 Returns a list of all loaded Erlang modules (current and old
3355 code), including preloaded modules.
3356
3357 See also code(3).
3358
3359 erlang:localtime() -> DateTime
3360
3361 Types:
3362
3363 DateTime = calendar:datetime()
3364
3365 Returns the current local date and time, {{Year, Month, Day},
3366 {Hour, Minute, Second}}, for example:
3367
3368 > erlang:localtime().
3369 {{1996,11,6},{14,45,17}}
3370
3371 The time zone and Daylight Saving Time correction depend on the
3372 underlying OS. The return value is based on the OS System Time.
3373
3374 erlang:localtime_to_universaltime(Localtime) -> Universaltime
3375
3376 Types:
3377
3378 Localtime = Universaltime = calendar:datetime()
3379
3380 Converts local date and time to Universal Time Coordinated
3381 (UTC), if supported by the underlying OS. Otherwise no conver‐
3382 sion is done and Localtime is returned. Example:
3383
3384 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
3385 {{1996,11,6},{13,45,17}}
3386
3387 Failure: badarg if Localtime denotes an invalid date and time.
3388
3389 erlang:localtime_to_universaltime(Localtime, IsDst) ->
3390 Universaltime
3391
3392 Types:
3393
3394 Localtime = Universaltime = calendar:datetime()
3395 IsDst = true | false | undefined
3396
3397 Converts local date and time to Universal Time Coordinated (UTC)
3398 as erlang:localtime_to_universaltime/1, but the caller decides
3399 if Daylight Saving Time is active.
3400
3401 If IsDst == true, Localtime is during Daylight Saving Time, if
3402 IsDst == false it is not. If IsDst == undefined, the underlying
3403 OS can guess, which is the same as calling erlang:local‐
3404 time_to_universaltime(Localtime).
3405
3406 Examples:
3407
3408 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
3409 {{1996,11,6},{12,45,17}}
3410 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
3411 {{1996,11,6},{13,45,17}}
3412 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
3413 {{1996,11,6},{13,45,17}}
3414
3415 Failure: badarg if Localtime denotes an invalid date and time.
3416
3417 make_ref() -> reference()
3418
3419 Returns a unique reference. The reference is unique among con‐
3420 nected nodes.
3421
3422 Warning:
3423 Before OTP-23 when a node is restarted multiple times with the
3424 same node name, references created on a newer node can be mis‐
3425 taken for a reference created on an older node with the same
3426 node name.
3427
3428
3429 erlang:make_tuple(Arity, InitialValue) -> tuple()
3430
3431 Types:
3432
3433 Arity = arity()
3434 InitialValue = term()
3435
3436 Creates a new tuple of the specified Arity, where all elements
3437 are InitialValue, for example:
3438
3439 > erlang:make_tuple(4, []).
3440 {[],[],[],[]}
3441
3442 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3443
3444 Types:
3445
3446 Arity = arity()
3447 DefaultValue = term()
3448 InitList = [{Position :: integer() >= 1, term()}]
3449
3450 Creates a tuple of size Arity, where each element has value De‐
3451 faultValue, and then fills in values from InitList. Each list
3452 element in InitList must be a two-tuple, where the first element
3453 is a position in the newly created tuple and the second element
3454 is any term. If a position occurs more than once in the list,
3455 the term corresponding to the last occurrence is used. Example:
3456
3457 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3458 {[],aa,[],[],zz}
3459
3460 map_get(Key, Map) -> Value
3461
3462 Types:
3463
3464 Map = map()
3465 Key = Value = any()
3466
3467 Returns value Value associated with Key if Map contains Key.
3468
3469 The call fails with a {badmap,Map} exception if Map is not a
3470 map, or with a {badkey,Key} exception if no value is associated
3471 with Key.
3472
3473 Example:
3474
3475 > Key = 1337,
3476 Map = #{42 => value_two,1337 => "value one","a" => 1},
3477 map_get(Key,Map).
3478 "value one"
3479
3480 Allowed in guard tests.
3481
3482 map_size(Map) -> integer() >= 0
3483
3484 Types:
3485
3486 Map = map()
3487
3488 Returns an integer, which is the number of key-value pairs in
3489 Map, for example:
3490
3491 > map_size(#{a=>1, b=>2, c=>3}).
3492 3
3493
3494 Allowed in guard tests.
3495
3496 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3497 TestResult
3498
3499 Types:
3500
3501 MatchAgainst = [term()] | tuple()
3502 MatchSpec = term()
3503 Type = table | trace
3504 TestResult =
3505 {ok, term(), [return_trace], [{error | warning,
3506 string()}]} |
3507 {error, [{error | warning, string()}]}
3508
3509 Tests a match specification used in calls to ets:select/2 and
3510 erlang:trace_pattern/3. The function tests both a match specifi‐
3511 cation for "syntactic" correctness and runs the match specifica‐
3512 tion against the object. If the match specification contains er‐
3513 rors, the tuple {error, Errors} is returned, where Errors is a
3514 list of natural language descriptions of what was wrong with the
3515 match specification.
3516
3517 If Type is table, the object to match against is to be a tuple.
3518 The function then returns {ok,Result,[],Warnings}, where Result
3519 is what would have been the result in a real ets:select/2 call,
3520 or false if the match specification does not match the object
3521 tuple.
3522
3523 If Type is trace, the object to match against is to be a list.
3524 The function returns {ok, Result, Flags, Warnings}, where Result
3525 is one of the following:
3526
3527 * true if a trace message is to be emitted
3528
3529 * false if a trace message is not to be emitted
3530
3531 * The message term to be appended to the trace message
3532
3533 Flags is a list containing all the trace flags to be enabled,
3534 currently this is only return_trace.
3535
3536 This is a useful debugging and test tool, especially when writ‐
3537 ing complicated match specifications.
3538
3539 See also ets:test_ms/2.
3540
3541 max(Term1, Term2) -> Maximum
3542
3543 Types:
3544
3545 Term1 = Term2 = Maximum = term()
3546
3547 Returns the largest of Term1 and Term2. If the terms compare
3548 equal with the == operator, Term1 is returned.
3549
3550 The Expressions section contains descriptions of the == opera‐
3551 tor and how terms are ordered.
3552
3553 Examples:
3554
3555 > max(1, 2).
3556 2
3557
3558 > max(1.0, 1).
3559 1.0
3560
3561 > max(1, 1.0).
3562 1
3563
3564 > max("abc", "b").
3565 "b"
3566
3567 erlang:md5(Data) -> Digest
3568
3569 Types:
3570
3571 Data = iodata()
3572 Digest = binary()
3573
3574 Computes an MD5 message digest from Data, where the length of
3575 the digest is 128 bits (16 bytes). Data is a binary or a list of
3576 small integers and binaries.
3577
3578 For more information about MD5, see RFC 1321 - The MD5 Message-
3579 Digest Algorithm.
3580
3581 Warning:
3582 The MD5 Message-Digest Algorithm is not considered safe for
3583 code-signing or software-integrity purposes.
3584
3585
3586 erlang:md5_final(Context) -> Digest
3587
3588 Types:
3589
3590 Context = Digest = binary()
3591
3592 Finishes the update of an MD5 Context and returns the computed
3593 MD5 message digest.
3594
3595 erlang:md5_init() -> Context
3596
3597 Types:
3598
3599 Context = binary()
3600
3601 Creates an MD5 context, to be used in the following calls to
3602 md5_update/2.
3603
3604 erlang:md5_update(Context, Data) -> NewContext
3605
3606 Types:
3607
3608 Context = binary()
3609 Data = iodata()
3610 NewContext = binary()
3611
3612 Update an MD5 Context with Data and returns a NewContext.
3613
3614 erlang:memory() -> [{Type, Size}]
3615
3616 Types:
3617
3618 Type = memory_type()
3619 Size = integer() >= 0
3620 memory_type() =
3621 total | processes | processes_used | system | atom |
3622 atom_used | binary | code | ets
3623
3624 Returns a list with information about memory dynamically allo‐
3625 cated by the Erlang emulator. Each list element is a tuple
3626 {Type, Size}. The first element Type is an atom describing mem‐
3627 ory type. The second element Size is the memory size in bytes.
3628
3629 Memory types:
3630
3631 total:
3632 The total amount of memory currently allocated. This is the
3633 same as the sum of the memory size for processes and system.
3634
3635 processes:
3636 The total amount of memory currently allocated for the Er‐
3637 lang processes.
3638
3639 processes_used:
3640 The total amount of memory currently used by the Erlang pro‐
3641 cesses. This is part of the memory presented as processes
3642 memory.
3643
3644 system:
3645 The total amount of memory currently allocated for the emu‐
3646 lator that is not directly related to any Erlang process.
3647 Memory presented as processes is not included in this mem‐
3648 ory. instrument(3) can be used to get a more detailed break‐
3649 down of what memory is part of this type.
3650
3651 atom:
3652 The total amount of memory currently allocated for atoms.
3653 This memory is part of the memory presented as system mem‐
3654 ory.
3655
3656 atom_used:
3657 The total amount of memory currently used for atoms. This
3658 memory is part of the memory presented as atom memory.
3659
3660 binary:
3661 The total amount of memory currently allocated for binaries.
3662 This memory is part of the memory presented as system mem‐
3663 ory.
3664
3665 code:
3666 The total amount of memory currently allocated for Erlang
3667 code. This memory is part of the memory presented as system
3668 memory.
3669
3670 ets:
3671 The total amount of memory currently allocated for ETS ta‐
3672 bles. This memory is part of the memory presented as system
3673 memory.
3674
3675 maximum:
3676 The maximum total amount of memory allocated since the emu‐
3677 lator was started. This tuple is only present when the emu‐
3678 lator is run with instrumentation.
3679
3680 For information on how to run the emulator with instrumenta‐
3681 tion, see instrument(3) and/or erl(1).
3682
3683 Note:
3684 The system value is not complete. Some allocated memory that is
3685 to be part of this value is not.
3686
3687 When the emulator is run with instrumentation, the system value
3688 is more accurate, but memory directly allocated for malloc (and
3689 friends) is still not part of the system value. Direct calls to
3690 malloc are only done from OS-specific runtime libraries and per‐
3691 haps from user-implemented Erlang drivers that do not use the
3692 memory allocation functions in the driver interface.
3693
3694 As the total value is the sum of processes and system, the error
3695 in system propagates to the total value.
3696
3697 The different amounts of memory that are summed are not gathered
3698 atomically, which introduces an error in the result.
3699
3700
3701 The different values have the following relation to each other.
3702 Values beginning with an uppercase letter is not part of the re‐
3703 sult.
3704
3705 total = processes + system
3706 processes = processes_used + ProcessesNotUsed
3707 system = atom + binary + code + ets + OtherSystem
3708 atom = atom_used + AtomNotUsed
3709 RealTotal = processes + RealSystem
3710 RealSystem = system + MissedSystem
3711
3712 More tuples in the returned list can be added in a future re‐
3713 lease.
3714
3715 Note:
3716 The total value is supposed to be the total amount of memory dy‐
3717 namically allocated by the emulator. Shared libraries, the code
3718 of the emulator itself, and the emulator stacks are not supposed
3719 to be included. That is, the total value is not supposed to be
3720 equal to the total size of all pages mapped to the emulator.
3721
3722 Also, because of fragmentation and prereservation of memory ar‐
3723 eas, the size of the memory segments containing the dynamically
3724 allocated memory blocks can be much larger than the total size
3725 of the dynamically allocated memory blocks.
3726
3727
3728 Note:
3729 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
3730 loc(3) allocators are enabled (default behavior).
3731
3732
3733 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3734
3735 erlang:memory(Type :: memory_type()) -> integer() >= 0
3736
3737 erlang:memory(TypeList :: [memory_type()]) ->
3738 [{memory_type(), integer() >= 0}]
3739
3740 Types:
3741
3742 memory_type() =
3743 total | processes | processes_used | system | atom |
3744 atom_used | binary | code | ets
3745
3746 Returns the memory size in bytes allocated for memory of type
3747 Type. The argument can also be specified as a list of mem‐
3748 ory_type() atoms, in which case a corresponding list of {mem‐
3749 ory_type(), Size :: integer >= 0} tuples is returned.
3750
3751 Note:
3752 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
3753 loc(3) allocators are enabled (default behavior).
3754
3755
3756 Failures:
3757
3758 badarg:
3759 If Type is not one of the memory types listed in the de‐
3760 scription of erlang:memory/0.
3761
3762 badarg:
3763 If maximum is passed as Type and the emulator is not run in
3764 instrumented mode.
3765
3766 notsup:
3767 If an erts_alloc(3) allocator has been disabled.
3768
3769 See also erlang:memory/0.
3770
3771 min(Term1, Term2) -> Minimum
3772
3773 Types:
3774
3775 Term1 = Term2 = Minimum = term()
3776
3777 Returns the smallest of Term1 and Term2. If the terms compare
3778 equal with the == operator, Term1 is returned.
3779
3780 The Expressions section contains descriptions of the == opera‐
3781 tor and how terms are ordered.
3782
3783 Examples:
3784
3785 > min(1, 2).
3786 1
3787
3788 > min(1.0, 1).
3789 1.0
3790
3791 > min(1, 1.0).
3792 1
3793
3794 > min("abc", "b").
3795 "abc"
3796
3797 module_loaded(Module) -> boolean()
3798
3799 Types:
3800
3801 Module = module()
3802
3803 Returns true if the module Module is loaded, otherwise false. It
3804 does not attempt to load the module.
3805
3806 Warning:
3807 This BIF is intended for the code server (see code(3)) and is
3808 not to be used elsewhere.
3809
3810
3811 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3812 MonitorRef
3813
3814 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3815 MonitorRef
3816
3817 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3818
3819 Types:
3820
3821 MonitorRef = reference()
3822 registered_name() = atom()
3823 registered_process_identifier() =
3824 registered_name() | {registered_name(), node()}
3825 monitor_process_identifier() =
3826 pid() | registered_process_identifier()
3827 monitor_port_identifier() = port() | registered_name()
3828
3829 Sends a monitor request of type Type to the entity identified by
3830 Item. If the monitored entity does not exist or it changes moni‐
3831 tored state, the caller of monitor/2 is notified by a message on
3832 the following format:
3833
3834 {Tag, MonitorRef, Type, Object, Info}
3835
3836 Note:
3837 The monitor request is an asynchronous signal. That is, it takes
3838 time before the signal reaches its destination.
3839
3840
3841 Type can be one of the following atoms: process, port or
3842 time_offset.
3843
3844 A process or port monitor is triggered only once, after that it
3845 is removed from both monitoring process and the monitored en‐
3846 tity. Monitors are fired when the monitored process or port ter‐
3847 minates, does not exist at the moment of creation, or if the
3848 connection to it is lost. If the connection to it is lost, we do
3849 not know if it still exists. The monitoring is also turned off
3850 when demonitor/1 is called.
3851
3852 A process or port monitor by name resolves the RegisteredName to
3853 pid() or port() only once at the moment of monitor instantia‐
3854 tion, later changes to the name registration will not affect the
3855 existing monitor.
3856
3857 When a process or port monitor is triggered, a 'DOWN' message is
3858 sent that has the following pattern:
3859
3860 {'DOWN', MonitorRef, Type, Object, Info}
3861
3862 In the monitor message MonitorRef and Type are the same as de‐
3863 scribed earlier, and:
3864
3865 Object:
3866 The monitored entity, which triggered the event. When moni‐
3867 toring a process or a local port, Object will be equal to
3868 the pid() or port() that was being monitored. When monitor‐
3869 ing process or port by name, Object will have format {Regis‐
3870 teredName, Node} where RegisteredName is the name which has
3871 been used with monitor/2 call and Node is local or remote
3872 node name (for ports monitored by name, Node is always local
3873 node name).
3874
3875 Info:
3876 Either the exit reason of the process, noproc (process or
3877 port did not exist at the time of monitor creation), or no‐
3878 connection (no connection to the node where the monitored
3879 process resides).
3880
3881 Monitoring a process:
3882 Creates monitor between the current process and another
3883 process identified by Item, which can be a pid() (local or
3884 remote), an atom RegisteredName or a tuple {RegisteredName,
3885 Node} for a registered process, located elsewhere.
3886
3887 Note:
3888 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3889 with badarg if the monitored process resided on a primitive
3890 node (such as erl_interface or jinterface), where remote
3891 process monitoring is not implemented.
3892
3893 Now, such a call to monitor will instead succeed and a monitor
3894 is created. But the monitor will only supervise the connec‐
3895 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3896 only message that may be received, as the primitive node have
3897 no way of reporting the status of the monitored process.
3898
3899
3900 Monitoring a port:
3901 Creates monitor between the current process and a port iden‐
3902 tified by Item, which can be a port() (only local), an atom
3903 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3904 istered port, located on this node. Note, that attempt to
3905 monitor a remote port will result in badarg.
3906
3907 Monitoring a time_offset:
3908 Monitors changes in time offset between Erlang monotonic
3909 time and Erlang system time. One valid Item exists in combi‐
3910 nation with the time_offset Type, namely the atom clock_ser‐
3911 vice. Notice that the atom clock_service is not the regis‐
3912 tered name of a process. In this case it serves as an iden‐
3913 tifier of the runtime system internal clock service at cur‐
3914 rent runtime system instance.
3915
3916 The monitor is triggered when the time offset is changed.
3917 This either if the time offset value is changed, or if the
3918 offset is changed from preliminary to final during finaliza‐
3919 tion of the time offset when the single time warp mode is
3920 used. When a change from preliminary to final time offset is
3921 made, the monitor is triggered once regardless of whether
3922 the time offset value was changed or not.
3923
3924 If the runtime system is in multi time warp mode, the time
3925 offset is changed when the runtime system detects that the
3926 OS system time has changed. The runtime system does, how‐
3927 ever, not detect this immediately when it occurs. A task
3928 checking the time offset is scheduled to execute at least
3929 once a minute, so under normal operation this is to be de‐
3930 tected within a minute, but during heavy load it can take
3931 longer time.
3932
3933 The monitor is not automatically removed after it has been
3934 triggered. That is, repeated changes of the time offset
3935 trigger the monitor repeatedly.
3936
3937 When the monitor is triggered a 'CHANGE' message is sent to
3938 the monitoring process. A 'CHANGE' message has the following
3939 pattern:
3940
3941 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3942
3943 where MonitorRef, Type, and Item are the same as described
3944 above, and NewTimeOffset is the new time offset.
3945
3946 When the 'CHANGE' message has been received you are guaran‐
3947 teed not to retrieve the old time offset when calling er‐
3948 lang:time_offset(). Notice that you can observe the change
3949 of the time offset when calling erlang:time_offset() before
3950 you get the 'CHANGE' message.
3951
3952 Making several calls to monitor/2 for the same Item and/or Type
3953 is not an error; it results in as many independent monitoring
3954 instances.
3955
3956 The monitor functionality is expected to be extended. That is,
3957 other Types and Items are expected to be supported in a future
3958 release.
3959
3960 Note:
3961 If or when monitor/2 is extended, other possible values for Tag,
3962 Object, and Info in the monitor message will be introduced.
3963
3964
3965 monitor(Type :: process,
3966 Item :: monitor_process_identifier(),
3967 Opts :: [monitor_option()]) ->
3968 MonitorRef
3969
3970 monitor(Type :: port,
3971 Item :: monitor_port_identifier(),
3972 Opts :: [monitor_option()]) ->
3973 MonitorRef
3974
3975 monitor(Type :: time_offset,
3976 Item :: clock_service,
3977 Opts :: [monitor_option()]) ->
3978 MonitorRef
3979
3980 Types:
3981
3982 MonitorRef = reference()
3983 registered_name() = atom()
3984 registered_process_identifier() =
3985 registered_name() | {registered_name(), node()}
3986 monitor_process_identifier() =
3987 pid() | registered_process_identifier()
3988 monitor_port_identifier() = port() | registered_name()
3989
3990 Provides an option list for modification of monitoring function‐
3991 ality provided by monitor/2. The Type and Item arguments have
3992 the same meaning as when passed to monitor/2. Currently avail‐
3993 able options:
3994
3995 {alias, UnaliasOpt}:
3996 The returned monitor reference will also become an alias for
3997 the calling process. That is, the returned reference can be
3998 used for sending messages to the calling process. See also
3999 alias/0. The UnaliasOpt determines how the alias should be
4000 deactivated.
4001
4002 explicit_unalias:
4003 Only an explicit call to unalias/1 will deactivate the
4004 alias.
4005
4006 demonitor:
4007 The alias will be automatically deactivated when the moni‐
4008 tor is removed. This either via an explicit call to demon‐
4009 itor/1 or when it is automatically removed at the same
4010 time as a 'DOWN' message is delivered due to the monitor.
4011 The alias can also still be deactivated via a call to una‐
4012 lias/1.
4013
4014 reply_demonitor:
4015 The alias will be automatically deactivated when the moni‐
4016 tor is removed (see demonitor option above) or a reply
4017 message sent via the alias is received. When a reply mes‐
4018 sage is received via the alias the monitor will also be
4019 automatically removed. This is useful in client/server
4020 scenarios when a client monitors the server and will get
4021 the reply via the alias. Once the response is received
4022 both the alias and the monitor will be automatically re‐
4023 moved regardless of whether the response is a reply or a
4024 'DOWN' message. The alias can also still be deactivated
4025 via a call to unalias/1. Note that if the alias is removed
4026 using the unalias/1 BIF, the monitor will still be left
4027 active.
4028
4029 Example:
4030
4031 server() ->
4032 receive
4033 {request, AliasReqId, Request} ->
4034 Result = perform_request(Request),
4035 AliasReqId ! {reply, AliasReqId, Result}
4036 end,
4037 server().
4038
4039 client(ServerPid, Request) ->
4040 AliasMonReqId = monitor(process, ServerPid, [{alias, reply_demonitor}]),
4041 ServerPid ! {request, AliasMonReqId, Request},
4042 %% Alias as well as monitor will be automatically deactivated if we
4043 %% receive a reply or a 'DOWN' message since we used 'reply_demonitor'
4044 %% as unalias option...
4045 receive
4046 {reply, AliasMonReqId, Result} ->
4047 Result;
4048 {'DOWN', AliasMonReqId, process, ServerPid, ExitReason} ->
4049 error(ExitReason)
4050 end.
4051
4052
4053 Note that both the server and the client in this example
4054 must be executing on at least OTP 24 systems in order for
4055 this to work.
4056
4057 For more information on process aliases see the Process
4058 Aliases section of the Erlang Reference Manual .
4059
4060 {tag, UserDefinedTag}:
4061 Replace the default Tag with UserDefinedTag in the monitor
4062 message delivered when the monitor is triggered. For exam‐
4063 ple, when monitoring a process, the 'DOWN' tag in the down
4064 message will be replaced by UserDefinedTag.
4065
4066 An example of how the {tag, UserDefinedTag} option can be
4067 used in order to enable the new selective receive optimiza‐
4068 tion, introduced in OTP 24, when making multiple requests to
4069 different servers:
4070
4071 server() ->
4072 receive
4073 {request, From, ReqId, Request} ->
4074 Result = perform_request(Request),
4075 From ! {reply, self(), ReqId, Result}
4076 end,
4077 server().
4078
4079 client(ServerPids, Request) when is_list(ServerPids) ->
4080 ReqId = make_ref(),
4081 lists:foreach(fun (ServerPid) ->
4082 _ = monitor(process, ServerPid,
4083 [{tag, {'DOWN', ReqId}}]),
4084 ServerPid ! {request, self(), ReqId, Request}
4085 end,
4086 ServerPids),
4087 receive_replies(ReqId, length(ServerPids), []).
4088
4089 receive_replies(_ReqId, 0, Acc) ->
4090 Acc;
4091 receive_replies(ReqId, N, Acc) ->
4092 %% The compiler will detect that we match on the 'ReqId'
4093 %% reference in all clauses, and will enable the selective
4094 %% receive optimization which makes the receive able to
4095 %% skip past all messages present in the message queue at
4096 %% the time when the 'ReqId' reference was created...
4097 Res = receive
4098 {reply, ServerPid, ReqId, Result} ->
4099 %% Here we typically would have deactivated the
4100 %% monitor by a call to demonitor(Mon, [flush]) but
4101 %% we ignore this in this example for simplicity...
4102 {ok, ServerPid, Result};
4103 {{'DOWN', ReqId}, _Mon, process, ServerPid, ExitReason} ->
4104 {error, ServerPid, ExitReason}
4105 end,
4106 receive_replies(ReqId, N-1, [Res | Acc]).
4107
4108
4109 In order for this example to work as intended, the client
4110 must be executing on at least an OTP 24 system, but the
4111 servers may execute on older systems.
4112
4113 monitor_node(Node, Flag) -> true
4114
4115 Types:
4116
4117 Node = node()
4118 Flag = boolean()
4119
4120 Monitor the status of the node Node. If Flag is true, monitoring
4121 is turned on. If Flag is false, monitoring is turned off.
4122
4123 Making several calls to monitor_node(Node, true) for the same
4124 Node is not an error; it results in as many independent monitor‐
4125 ing instances.
4126
4127 If Node fails or does not exist, the message {nodedown, Node} is
4128 delivered to the process. If a process has made two calls to
4129 monitor_node(Node, true) and Node terminates, two nodedown mes‐
4130 sages are delivered to the process. If there is no connection to
4131 Node, an attempt is made to create one. If this fails, a node‐
4132 down message is delivered.
4133
4134 The delivery of the nodedown signal is not ordered with respect
4135 to other link or monitor signals from the node that goes down.
4136 If you need a guarantee that all signals from the remote node
4137 has been delivered before the nodedown signal is sent, you
4138 should use net_kernel:monitor_nodes/1.
4139
4140 Nodes connected through hidden connections can be monitored as
4141 any other nodes.
4142
4143 Failure: notalive if the local node is not alive.
4144
4145 erlang:monitor_node(Node, Flag, Options) -> true
4146
4147 Types:
4148
4149 Node = node()
4150 Flag = boolean()
4151 Options = [Option]
4152 Option = allow_passive_connect
4153
4154 Behaves as monitor_node/2 except that it allows an extra option
4155 to be specified, namely allow_passive_connect. This option al‐
4156 lows the BIF to wait the normal network connection time-out for
4157 the monitored node to connect itself, even if it cannot be ac‐
4158 tively connected from this node (that is, it is blocked). The
4159 state where this can be useful can only be achieved by using the
4160 Kernel option dist_auto_connect once. If that option is not
4161 used, option allow_passive_connect has no effect.
4162
4163 Note:
4164 Option allow_passive_connect is used internally and is seldom
4165 needed in applications where the network topology and the Kernel
4166 options in effect are known in advance.
4167
4168
4169 Failure: badarg if the local node is not alive or the option
4170 list is malformed.
4171
4172 erlang:monotonic_time() -> integer()
4173
4174 Returns the current Erlang monotonic time in native time unit.
4175 This is a monotonically increasing time since some unspecified
4176 point in time.
4177
4178 Note:
4179 This is a monotonically increasing time, but not a strictly
4180 monotonically increasing time. That is, consecutive calls to er‐
4181 lang:monotonic_time/0 can produce the same result.
4182
4183 Different runtime system instances will use different unspeci‐
4184 fied points in time as base for their Erlang monotonic clocks.
4185 That is, it is pointless comparing monotonic times from differ‐
4186 ent runtime system instances. Different runtime system instances
4187 can also place this unspecified point in time different relative
4188 runtime system start. It can be placed in the future (time at
4189 start is a negative value), the past (time at start is a posi‐
4190 tive value), or the runtime system start (time at start is
4191 zero). The monotonic time at runtime system start can be re‐
4192 trieved by calling erlang:system_info(start_time).
4193
4194
4195 erlang:monotonic_time(Unit) -> integer()
4196
4197 Types:
4198
4199 Unit = time_unit()
4200
4201 Returns the current Erlang monotonic time converted into the
4202 Unit passed as argument.
4203
4204 Same as calling erlang:convert_time_unit(erlang:mono‐
4205 tonic_time(), native, Unit), however optimized for commonly used
4206 Units.
4207
4208 erlang:nif_error(Reason) -> no_return()
4209
4210 Types:
4211
4212 Reason = term()
4213
4214 Works exactly like error/1, but Dialyzer thinks that this BIF
4215 will return an arbitrary term. When used in a stub function for
4216 a NIF to generate an exception when the NIF library is not
4217 loaded, Dialyzer does not generate false warnings.
4218
4219 erlang:nif_error(Reason, Args) -> no_return()
4220
4221 Types:
4222
4223 Reason = term()
4224 Args = [term()]
4225
4226 Works exactly like error/2, but Dialyzer thinks that this BIF
4227 will return an arbitrary term. When used in a stub function for
4228 a NIF to generate an exception when the NIF library is not
4229 loaded, Dialyzer does not generate false warnings.
4230
4231 node() -> Node
4232
4233 Types:
4234
4235 Node = node()
4236
4237 Returns the name of the local node. If the node is not alive,
4238 nonode@nohost is returned instead.
4239
4240 Allowed in guard tests.
4241
4242 node(Arg) -> Node
4243
4244 Types:
4245
4246 Arg = pid() | port() | reference()
4247 Node = node()
4248
4249 Returns the node where Arg originates. Arg can be a process
4250 identifier, a reference, or a port. If Arg originates from the
4251 local node and the local node is not alive, nonode@nohost is re‐
4252 turned.
4253
4254 Allowed in guard tests.
4255
4256 nodes() -> Nodes
4257
4258 Types:
4259
4260 Nodes = [node()]
4261
4262 Returns a list of all nodes connected to this node through nor‐
4263 mal connections (that is, hidden nodes are not listed). Same as
4264 nodes(visible).
4265
4266 nodes(Arg) -> Nodes
4267
4268 Types:
4269
4270 Arg = NodeType | [NodeType]
4271 NodeType = visible | hidden | connected | this | known
4272 Nodes = [node()]
4273
4274 Returns a list of nodes according to the argument specified. The
4275 returned result, when the argument is a list, is the list of
4276 nodes satisfying the disjunction(s) of the list elements.
4277
4278 NodeTypes:
4279
4280 visible:
4281 Nodes connected to this node through normal connections.
4282
4283 hidden:
4284 Nodes connected to this node through hidden connections.
4285
4286 connected:
4287 All nodes connected to this node.
4288
4289 this:
4290 This node.
4291
4292 known:
4293 Nodes that are known to this node. That is, connected nodes
4294 and nodes referred to by process identifiers, port identi‐
4295 fiers, and references located on this node. The set of known
4296 nodes is garbage collected. Notice that this garbage collec‐
4297 tion can be delayed. For more information, see erlang:sys‐
4298 tem_info(delayed_node_table_gc).
4299
4300 Some equalities: [node()] = nodes(this), nodes(connected) =
4301 nodes([visible, hidden]), and nodes() = nodes(visible).
4302
4303 now() -> Timestamp
4304
4305 Types:
4306
4307 Timestamp = timestamp()
4308 timestamp() =
4309 {MegaSecs :: integer() >= 0,
4310 Secs :: integer() >= 0,
4311 MicroSecs :: integer() >= 0}
4312
4313 Warning:
4314 This function is deprecated. Do not use it.
4315
4316 For more information, see section Time and Time Correction in
4317 the User's Guide. Specifically, section Dos and Dont's de‐
4318 scribes what to use instead of erlang:now/0.
4319
4320
4321 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
4322 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
4323 provided by the underlying OS. Otherwise some other point in
4324 time is chosen. It is also guaranteed that the following calls
4325 to this BIF return continuously increasing values. Hence, the
4326 return value from erlang:now/0 can be used to generate unique
4327 time stamps. If it is called in a tight loop on a fast machine,
4328 the time of the node can become skewed.
4329
4330 Can only be used to check the local time of day if the time-zone
4331 information of the underlying OS is properly configured.
4332
4333 open_port(PortName, PortSettings) -> port()
4334
4335 Types:
4336
4337 PortName =
4338 {spawn, Command :: string() | binary()} |
4339 {spawn_driver, Command :: string() | binary()} |
4340 {spawn_executable, FileName :: file:name_all()} |
4341 {fd, In :: integer() >= 0, Out :: integer() >= 0}
4342 PortSettings = [Opt]
4343 Opt =
4344 {packet, N :: 1 | 2 | 4} |
4345 stream |
4346 {line, L :: integer() >= 0} |
4347 {cd, Dir :: string() | binary()} |
4348 {env,
4349 Env ::
4350 [{Name :: os:env_var_name(),
4351 Val :: os:env_var_value() | false}]} |
4352 {args, [string() | binary()]} |
4353 {arg0, string() | binary()} |
4354 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
4355 |
4356 in | out | binary | eof |
4357 {parallelism, Boolean :: boolean()} |
4358 hide |
4359 {busy_limits_port,
4360 {integer() >= 0, integer() >= 0} | disabled} |
4361 {busy_limits_msgq,
4362 {integer() >= 0, integer() >= 0} | disabled}
4363
4364 Returns a port identifier as the result of opening a new Erlang
4365 port. A port can be seen as an external Erlang process.
4366
4367 The name of the executable as well as the arguments specifed in
4368 cd, env, args, and arg0 are subject to Unicode filename transla‐
4369 tion if the system is running in Unicode filename mode. To avoid
4370 translation or to force, for example UTF-8, supply the exe‐
4371 cutable and/or arguments as a binary in the correct encoding.
4372 For details, see the module file(3), the function file:na‐
4373 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
4374 User's Guide.
4375
4376 Note:
4377 The characters in the name (if specified as a list) can only be
4378 > 255 if the Erlang virtual machine is started in Unicode file‐
4379 name translation mode. Otherwise the name of the executable is
4380 limited to the ISO Latin-1 character set.
4381
4382
4383 PortNames:
4384
4385 {spawn, Command}:
4386 Starts an external program. Command is the name of the ex‐
4387 ternal program to be run. Command runs outside the Erlang
4388 work space unless an Erlang driver with the name Command is
4389 found. If found, that driver is started. A driver runs in
4390 the Erlang work space, which means that it is linked with
4391 the Erlang runtime system.
4392
4393 For external programs, PATH is searched (or an equivalent
4394 method is used to find programs, depending on the OS). This
4395 is done by invoking the shell on certain platforms. The
4396 first space-separated token of the command is considered as
4397 the name of the executable (or driver). This (among other
4398 things) makes this option unsuitable for running programs
4399 with spaces in filenames or directory names. If spaces in
4400 executable filenames are desired, use {spawn_executable,
4401 Command} instead.
4402
4403 {spawn_driver, Command}:
4404 Works like {spawn, Command}, but demands the first (space-
4405 separated) token of the command to be the name of a loaded
4406 driver. If no driver with that name is loaded, a badarg er‐
4407 ror is raised.
4408
4409 {spawn_executable, FileName}:
4410 Works like {spawn, FileName}, but only runs external exe‐
4411 cutables. FileName in its whole is used as the name of the
4412 executable, including any spaces. If arguments are to be
4413 passed, the PortSettings args and arg0 can be used.
4414
4415 The shell is usually not invoked to start the program, it is
4416 executed directly. PATH (or equivalent) is not searched. To
4417 find a program in PATH to execute, use os:find_executable/1.
4418
4419 Only if a shell script or .bat file is executed, the appro‐
4420 priate command interpreter is invoked implicitly, but there
4421 is still no command-argument expansion or implicit PATH
4422 search.
4423
4424 If FileName cannot be run, an error exception is raised,
4425 with the POSIX error code as the reason. The error reason
4426 can differ between OSs. Typically the error enoent is raised
4427 when an attempt is made to run a program that is not found
4428 and eacces is raised when the specified file is not exe‐
4429 cutable.
4430
4431 {fd, In, Out}:
4432 Allows an Erlang process to access any currently opened file
4433 descriptors used by Erlang. The file descriptor In can be
4434 used for standard input, and the file descriptor Out for
4435 standard output. It is only used for various servers in the
4436 Erlang OS (shell and user). Hence, its use is limited.
4437
4438 PortSettings is a list of settings for the port. The valid set‐
4439 tings are as follows:
4440
4441 {packet, N}:
4442 Messages are preceded by their length, sent in N bytes, with
4443 the most significant byte first. The valid values for N are
4444 1, 2, and 4.
4445
4446 stream:
4447 Output messages are sent without packet lengths. A user-de‐
4448 fined protocol must be used between the Erlang process and
4449 the external object.
4450
4451 {line, L}:
4452 Messages are delivered on a per line basis. Each line (de‐
4453 limited by the OS-dependent newline sequence) is delivered
4454 in a single message. The message data format is {Flag,
4455 Line}, where Flag is eol or noeol, and Line is the data de‐
4456 livered (without the newline sequence).
4457
4458 L specifies the maximum line length in bytes. Lines longer
4459 than this are delivered in more than one message, with Flag
4460 set to noeol for all but the last message. If end of file is
4461 encountered anywhere else than immediately following a new‐
4462 line sequence, the last line is also delivered with Flag set
4463 to noeol. Otherwise lines are delivered with Flag set to
4464 eol.
4465
4466 The {packet, N} and {line, L} settings are mutually exclu‐
4467 sive.
4468
4469 {cd, Dir}:
4470 Only valid for {spawn, Command} and {spawn_executable, File‐
4471 Name}. The external program starts using Dir as its working
4472 directory. Dir must be a string.
4473
4474 {env, Env}:
4475 Types:
4476 Name = os:env_var_name()
4477 Val = os:env_var_value() | false
4478 Env = [{Name, Val}]
4479
4480 Only valid for {spawn, Command}, and {spawn_executable,
4481 FileName}. The environment of the started process is ex‐
4482 tended using the environment specifications in Env.
4483
4484 Env is to be a list of tuples {Name, Val}, where Name is the
4485 name of an environment variable, and Val is the value it is
4486 to have in the spawned port process. Both Name and Val must
4487 be strings. The one exception is Val being the atom false
4488 (in analogy with os:getenv/1, which removes the environment
4489 variable.
4490
4491 For information about encoding requirements, see documenta‐
4492 tion of the types for Name and Val.
4493
4494 {args, [ string() | binary() ]}:
4495 Only valid for {spawn_executable, FileName} and specifies
4496 arguments to the executable. Each argument is specified as a
4497 separate string and (on Unix) eventually ends up as one ele‐
4498 ment each in the argument vector. On other platforms, a sim‐
4499 ilar behavior is mimicked.
4500
4501 The arguments are not expanded by the shell before they are
4502 supplied to the executable. Most notably this means that
4503 file wildcard expansion does not occur. To expand wildcards
4504 for the arguments, use filelib:wildcard/1. Notice that even
4505 if the program is a Unix shell script, meaning that the
4506 shell ultimately is invoked, wildcard expansion does not oc‐
4507 cur, and the script is provided with the untouched argu‐
4508 ments. On Windows, wildcard expansion is always up to the
4509 program itself, therefore this is not an issue.
4510
4511 The executable name (also known as argv[0]) is not to be
4512 specified in this list. The proper executable name is auto‐
4513 matically used as argv[0], where applicable.
4514
4515 If you explicitly want to set the program name in the argu‐
4516 ment vector, option arg0 can be used.
4517
4518 {arg0, string() | binary()}:
4519 Only valid for {spawn_executable, FileName} and explicitly
4520 specifies the program name argument when running an exe‐
4521 cutable. This can in some circumstances, on some OSs, be de‐
4522 sirable. How the program responds to this is highly system-
4523 dependent and no specific effect is guaranteed.
4524
4525 exit_status:
4526 Only valid for {spawn, Command}, where Command refers to an
4527 external program, and for {spawn_executable, FileName}.
4528
4529 When the external process connected to the port exits, a
4530 message of the form {Port,{exit_status,Status}} is sent to
4531 the connected process, where Status is the exit status of
4532 the external process. If the program aborts on Unix, the
4533 same convention is used as the shells do (that is, 128+sig‐
4534 nal).
4535
4536 If option eof is specified also, the messages eof and
4537 exit_status appear in an unspecified order.
4538
4539 If the port program closes its stdout without exiting, op‐
4540 tion exit_status does not work.
4541
4542 use_stdio:
4543 Only valid for {spawn, Command} and {spawn_executable, File‐
4544 Name}. It allows the standard input and output (file de‐
4545 scriptors 0 and 1) of the spawned (Unix) process for commu‐
4546 nication with Erlang.
4547
4548 nouse_stdio:
4549 The opposite of use_stdio. It uses file descriptors 3 and 4
4550 for communication with Erlang.
4551
4552 stderr_to_stdout:
4553 Affects ports to external programs. The executed program
4554 gets its standard error file redirected to its standard out‐
4555 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
4556 clusive.
4557
4558 overlapped_io:
4559 Affects ports to external programs on Windows only. The
4560 standard input and standard output handles of the port pro‐
4561 gram are, if this option is supplied, opened with flag
4562 FILE_FLAG_OVERLAPPED, so that the port program can (and
4563 must) do overlapped I/O on its standard handles. This is not
4564 normally the case for simple port programs, but an option of
4565 value for the experienced Windows programmer. On all other
4566 platforms, this option is silently discarded.
4567
4568 in:
4569 The port can only be used for input.
4570
4571 out:
4572 The port can only be used for output.
4573
4574 binary:
4575 All I/O from the port is binary data objects as opposed to
4576 lists of bytes.
4577
4578 eof:
4579 The port is not closed at the end of the file and does not
4580 produce an exit signal. Instead, it remains open and a
4581 {Port, eof} message is sent to the process holding the port.
4582
4583 hide:
4584 When running on Windows, suppresses creation of a new con‐
4585 sole window when spawning the port program. (This option has
4586 no effect on other platforms.)
4587
4588 {parallelism, Boolean}:
4589
4590
4591 Sets scheduler hint for port parallelism. If set to true,
4592 the virtual machine schedules port tasks; when doing so, it
4593 improves parallelism in the system. If set to false, the
4594 virtual machine tries to perform port tasks immediately, im‐
4595 proving latency at the expense of parallelism. The default
4596 can be set at system startup by passing command-line argu‐
4597 ment +spp to erl(1).
4598
4599 {busy_limits_port, {Low, High} | disabled}:
4600 Sets limits that will be used for controlling the busy state
4601 of the port.
4602
4603 When the ports internal output queue size becomes larger
4604 than or equal to High bytes, it enters the busy state. When
4605 it becomes less than Low bytes it leaves the busy state.
4606 When the port is in the busy state, processes sending com‐
4607 mands to it will be suspended until the port leaves the busy
4608 state. Commands are in this context either Port ! {Owner,
4609 {command, Data}} or port_command/[2,3].
4610
4611 The Low limit is automatically adjusted to the same as High
4612 if it is set larger then High. Valid range of values for Low
4613 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4614 If the atom disabled is passed, the port will never enter
4615 the busy state.
4616
4617 The defaults are Low = 4096 and High = 8192.
4618
4619 Note that this option is only valid when spawning an exe‐
4620 cutable (port program) by opening the spawn driver and when
4621 opening the fd driver. This option will cause a failure with
4622 a badarg exception when opening other drivers.
4623
4624 {busy_limits_msgq, {Low, High} | disabled}:
4625 Sets limits that will be used for controlling the busy state
4626 of the port message queue.
4627
4628 When the ports message queue size becomes larger than or
4629 equal to High bytes it enters the busy state. When it be‐
4630 comes less than Low bytes it leaves the busy state. When the
4631 port message queue is in the busy state, processes sending
4632 commands to it will be suspended until the port message
4633 queue leaves the busy state. Commands are in this context
4634 either Port ! {Owner, {command, Data}} or port_com‐
4635 mand/[2,3].
4636
4637 The Low limit is automatically adjusted to the same as High
4638 if it is set larger then High. Valid range of values for Low
4639 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4640 If the atom disabled is passed, the port message queue will
4641 never enter the busy state.
4642
4643 Note that if the driver statically has disabled the use of
4644 this feature, a failure with a badarg exception will be
4645 raised unless this option also is set to disable or not
4646 passed at all.
4647
4648 The defaults are Low = 4096 and High = 8192 unless the
4649 driver itself does modifications of these values.
4650
4651 Note that the driver might fail if it also adjust these lim‐
4652 its by itself and you have disabled this feature.
4653
4654 The spawn driver (used when spawning an executable) and the
4655 fd driver do not disable this feature and do not adjust
4656 these limits by themselves.
4657
4658 For more information see the documentation
4659 erl_drv_busy_msgq_limits().
4660
4661 Default is stream for all port types and use_stdio for spawned
4662 ports.
4663
4664 Failure: if the port cannot be opened, the exit reason is
4665 badarg, system_limit, or the POSIX error code that most closely
4666 describes the error, or einval if no POSIX code is appropriate:
4667
4668 badarg:
4669 Bad input arguments to open_port.
4670
4671 system_limit:
4672 All available ports in the Erlang emulator are in use.
4673
4674 enomem:
4675 Not enough memory to create the port.
4676
4677 eagain:
4678 No more available OS processes.
4679
4680 enametoolong:
4681 Too long external command.
4682
4683 emfile:
4684 No more available file descriptors (for the OS process that
4685 the Erlang emulator runs in).
4686
4687 enfile:
4688 Full file table (for the entire OS).
4689
4690 eacces:
4691 Command specified in {spawn_executable, Command} does not
4692 point out an executable file.
4693
4694 enoent:
4695 FileName specified in {spawn_executable, FileName} does not
4696 point out an existing file.
4697
4698 During use of a port opened using {spawn, Name}, {spawn_driver,
4699 Name}, or {spawn_executable, Name}, errors arising when sending
4700 messages to it are reported to the owning process using signals
4701 of the form {'EXIT', Port, PosixCode}. For the possible values
4702 of PosixCode, see file(3).
4703
4704 The maximum number of ports that can be open at the same time
4705 can be configured by passing command-line flag +Q to erl(1).
4706
4707 erlang:phash(Term, Range) -> Hash
4708
4709 Types:
4710
4711 Term = term()
4712 Range = Hash = integer() >= 1
4713 Range = 1..2^32, Hash = 1..Range
4714
4715 Warning:
4716 This function is deprecated as erlang:phash2/2 should be used
4717 for new code. Note that erlang:phash(X,N) is not necessary equal
4718 to erlang:phash2(X,N)
4719
4720
4721 Portable hash function that gives the same hash for the same Er‐
4722 lang term regardless of machine architecture and ERTS version
4723 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
4724 hash value for Term within the range 1..Range. The maximum value
4725 for Range is 2^32.
4726
4727 erlang:phash2(Term) -> Hash
4728
4729 erlang:phash2(Term, Range) -> Hash
4730
4731 Types:
4732
4733 Term = term()
4734 Range = integer() >= 1
4735 1..2^32
4736 Hash = integer() >= 0
4737 0..Range-1
4738
4739 Portable hash function that gives the same hash for the same Er‐
4740 lang term regardless of machine architecture and ERTS version
4741 (the BIF was introduced in ERTS 5.2). The function returns a
4742 hash value for Term within the range 0..Range-1. The maximum
4743 value for Range is 2^32. When without argument Range, a value in
4744 the range 0..2^27-1 is returned.
4745
4746 This BIF is always to be used for hashing terms. It distributes
4747 small integers better than phash/2, and it is faster for bignums
4748 and binaries.
4749
4750 Notice that the range 0..Range-1 is different from the range of
4751 phash/2, which is 1..Range.
4752
4753 pid_to_list(Pid) -> string()
4754
4755 Types:
4756
4757 Pid = pid()
4758
4759 Returns a string corresponding to the text representation of
4760 Pid. Example:
4761
4762 > erlang:pid_to_list(self()).
4763 "<0.85.0>"
4764
4765 Note:
4766 The creation for the node is not included in the list represen‐
4767 tation of Pid. This means that processes in different incarna‐
4768 tions of a node with a specific name can get the same list rep‐
4769 resentation.
4770
4771
4772 erlang:port_call(Port, Operation, Data) -> term()
4773
4774 Types:
4775
4776 Port = port() | atom()
4777 Operation = integer()
4778 Data = term()
4779
4780 Performs a synchronous call to a port. The meaning of Operation
4781 and Data depends on the port, that is, on the port driver. Not
4782 all port drivers support this feature.
4783
4784 Port is a port identifier, referring to a driver.
4785
4786 Operation is an integer, which is passed on to the driver.
4787
4788 Data is any Erlang term. This data is converted to binary term
4789 format and sent to the port.
4790
4791 Returns a term from the driver. The meaning of the returned data
4792 also depends on the port driver.
4793
4794 Failures:
4795
4796 badarg:
4797 If Port is not an identifier of an open port, or the regis‐
4798 tered name of an open port. If the calling process was pre‐
4799 viously linked to the closed port, identified by Port, the
4800 exit signal from the port is guaranteed to be delivered be‐
4801 fore this badarg exception occurs.
4802
4803 badarg:
4804 If Operation does not fit in a 32-bit integer.
4805
4806 badarg:
4807 If the port driver does not support synchronous control op‐
4808 erations.
4809
4810 badarg:
4811 If the port driver so decides for any reason (probably some‐
4812 thing wrong with Operation or Data).
4813
4814 Warning:
4815 Do not call port_call with an unknown Port identifier and ex‐
4816 pect badarg exception. Any undefined behavior is possible (in‐
4817 cluding node crash) depending on how the port driver inter‐
4818 prets the supplied arguments.
4819
4820
4821 port_close(Port) -> true
4822
4823 Types:
4824
4825 Port = port() | atom()
4826
4827 Closes an open port. Roughly the same as Port ! {self(), close}
4828 except for the error behavior (see below), being synchronous,
4829 and that the port does not reply with {Port, closed}. Any
4830 process can close a port with port_close/1, not only the port
4831 owner (the connected process). If the calling process is linked
4832 to the port identified by Port, the exit signal from the port is
4833 guaranteed to be delivered before port_close/1 returns.
4834
4835 For comparison: Port ! {self(), close} only fails with badarg if
4836 Port does not refer to a port or a process. If Port is a closed
4837 port, nothing happens. If Port is an open port and the calling
4838 process is the port owner, the port replies with {Port, closed}
4839 when all buffers have been flushed and the port really closes.
4840 If the calling process is not the port owner, the port owner
4841 fails with badsig.
4842
4843 Notice that any process can close a port using Port ! {Por‐
4844 tOwner, close} as if it itself was the port owner, but the reply
4845 always goes to the port owner.
4846
4847 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4848 chronous. Notice that this operation has always been documented
4849 as an asynchronous operation, while the underlying implementa‐
4850 tion has been synchronous. port_close/1 is however still fully
4851 synchronous because of its error behavior.
4852
4853 Failure: badarg if Port is not an identifier of an open port, or
4854 the registered name of an open port. If the calling process was
4855 previously linked to the closed port, identified by Port, the
4856 exit signal from the port is guaranteed to be delivered before
4857 this badarg exception occurs.
4858
4859 port_command(Port, Data) -> true
4860
4861 Types:
4862
4863 Port = port() | atom()
4864 Data = iodata()
4865
4866 Sends data to a port. Same as Port ! {PortOwner, {command,
4867 Data}} except for the error behavior and being synchronous (see
4868 below). Any process can send data to a port with port_command/2,
4869 not only the port owner (the connected process).
4870
4871 For comparison: Port ! {PortOwner, {command, Data}} only fails
4872 with badarg if Port does not refer to a port or a process. If
4873 Port is a closed port, the data message disappears without a
4874 sound. If Port is open and the calling process is not the port
4875 owner, the port owner fails with badsig. The port owner fails
4876 with badsig also if Data is an invalid I/O list.
4877
4878 Notice that any process can send to a port using Port ! {Por‐
4879 tOwner, {command, Data}} as if it itself was the port owner.
4880
4881 If the port is busy, the calling process is suspended until the
4882 port is not busy any more.
4883
4884 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4885 truly asynchronous. Notice that this operation has always been
4886 documented as an asynchronous operation, while the underlying
4887 implementation has been synchronous. port_command/2 is however
4888 still fully synchronous because of its error behavior.
4889
4890 Failures:
4891
4892 badarg:
4893 If Port is not an identifier of an open port, or the regis‐
4894 tered name of an open port. If the calling process was pre‐
4895 viously linked to the closed port, identified by Port, the
4896 exit signal from the port is guaranteed to be delivered be‐
4897 fore this badarg exception occurs.
4898
4899 badarg:
4900 If Data is an invalid I/O list.
4901
4902 Warning:
4903 Do not send data to an unknown port. Any undefined behavior is
4904 possible (including node crash) depending on how the port driver
4905 interprets the data.
4906
4907
4908 port_command(Port, Data, OptionList) -> boolean()
4909
4910 Types:
4911
4912 Port = port() | atom()
4913 Data = iodata()
4914 Option = force | nosuspend
4915 OptionList = [Option]
4916
4917 Sends data to a port. port_command(Port, Data, []) equals
4918 port_command(Port, Data).
4919
4920 If the port command is aborted, false is returned, otherwise
4921 true.
4922
4923 If the port is busy, the calling process is suspended until the
4924 port is not busy anymore.
4925
4926 Options:
4927
4928 force:
4929 The calling process is not suspended if the port is busy,
4930 instead the port command is forced through. The call fails
4931 with a notsup exception if the driver of the port does not
4932 support this. For more information, see driver flag
4933 ERL_DRV_FLAG_SOFT_BUSY.
4934
4935 nosuspend:
4936 The calling process is not suspended if the port is busy,
4937 instead the port command is aborted and false is returned.
4938
4939 Note:
4940 More options can be added in a future release.
4941
4942
4943 Failures:
4944
4945 badarg:
4946 If Port is not an identifier of an open port, or the regis‐
4947 tered name of an open port. If the calling process was pre‐
4948 viously linked to the closed port, identified by Port, the
4949 exit signal from the port is guaranteed to be delivered be‐
4950 fore this badarg exception occurs.
4951
4952 badarg:
4953 If Data is an invalid I/O list.
4954
4955 badarg:
4956 If OptionList is an invalid option list.
4957
4958 notsup:
4959 If option force has been passed, but the driver of the port
4960 does not allow forcing through a busy port.
4961
4962 Warning:
4963 Do not send data to an unknown port. Any undefined behavior is
4964 possible (including node crash) depending on how the port driver
4965 interprets the data.
4966
4967
4968 port_connect(Port, Pid) -> true
4969
4970 Types:
4971
4972 Port = port() | atom()
4973 Pid = pid()
4974
4975 Sets the port owner (the connected port) to Pid. Roughly the
4976 same as Port ! {Owner, {connect, Pid}} except for the following:
4977
4978 * The error behavior differs, see below.
4979
4980 * The port does not reply with {Port,connected}.
4981
4982 * port_connect/1 is synchronous, see below.
4983
4984 * The new port owner gets linked to the port.
4985
4986 The old port owner stays linked to the port and must call un‐
4987 link(Port) if this is not desired. Any process can set the port
4988 owner to be any process with port_connect/2.
4989
4990 For comparison: Port ! {self(), {connect, Pid}} only fails with
4991 badarg if Port does not refer to a port or a process. If Port is
4992 a closed port, nothing happens. If Port is an open port and the
4993 calling process is the port owner, the port replies with {Port,
4994 connected} to the old port owner. Notice that the old port owner
4995 is still linked to the port, while the new is not. If Port is an
4996 open port and the calling process is not the port owner, the
4997 port owner fails with badsig. The port owner fails with badsig
4998 also if Pid is not an existing local process identifier.
4999
5000 Notice that any process can set the port owner using Port !
5001 {PortOwner, {connect, Pid}} as if it itself was the port owner,
5002 but the reply always goes to the port owner.
5003
5004 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
5005 truly asynchronous. Notice that this operation has always been
5006 documented as an asynchronous operation, while the underlying
5007 implementation has been synchronous. port_connect/2 is however
5008 still fully synchronous because of its error behavior.
5009
5010 Failures:
5011
5012 badarg:
5013 If Port is not an identifier of an open port, or the regis‐
5014 tered name of an open port. If the calling process was pre‐
5015 viously linked to the closed port, identified by Port, the
5016 exit signal from the port is guaranteed to be delivered be‐
5017 fore this badarg exception occurs.
5018
5019 badarg:
5020 If the process identified by Pid is not an existing local
5021 process.
5022
5023 port_control(Port, Operation, Data) -> iodata() | binary()
5024
5025 Types:
5026
5027 Port = port() | atom()
5028 Operation = integer()
5029 Data = iodata()
5030
5031 Performs a synchronous control operation on a port. The meaning
5032 of Operation and Data depends on the port, that is, on the port
5033 driver. Not all port drivers support this control feature.
5034
5035 Returns a list of integers in the range 0..255, or a binary, de‐
5036 pending on the port driver. The meaning of the returned data
5037 also depends on the port driver.
5038
5039 Failures:
5040
5041 badarg:
5042 If Port is not an open port or the registered name of an
5043 open port.
5044
5045 badarg:
5046 If Operation cannot fit in a 32-bit integer.
5047
5048 badarg:
5049 If the port driver does not support synchronous control op‐
5050 erations.
5051
5052 badarg:
5053 If the port driver so decides for any reason (probably
5054 something wrong with Operation or Data).
5055
5056 Warning:
5057 Do not call port_control/3 with an unknown Port identifier and
5058 expect badarg exception. Any undefined behavior is possible
5059 (including node crash) depending on how the port driver inter‐
5060 prets the supplied arguments.
5061
5062
5063 erlang:port_info(Port) -> Result
5064
5065 Types:
5066
5067 Port = port() | atom()
5068 ResultItem =
5069 {registered_name, RegisteredName :: atom()} |
5070 {id, Index :: integer() >= 0} |
5071 {connected, Pid :: pid()} |
5072 {links, Pids :: [pid()]} |
5073 {name, String :: string()} |
5074 {input, Bytes :: integer() >= 0} |
5075 {output, Bytes :: integer() >= 0} |
5076 {os_pid, OsPid :: integer() >= 0 | undefined}
5077 Result = [ResultItem] | undefined
5078
5079 Returns a list containing tuples with information about Port, or
5080 undefined if the port is not open. The order of the tuples is
5081 undefined, and all the tuples are not mandatory. If the port is
5082 closed and the calling process was previously linked to the
5083 port, the exit signal from the port is guaranteed to be deliv‐
5084 ered before port_info/1 returns undefined.
5085
5086 The result contains information about the following Items:
5087
5088 * registered_name (if the port has a registered name)
5089
5090 * id
5091
5092 * connected
5093
5094 * links
5095
5096 * name
5097
5098 * input
5099
5100 * output
5101
5102 For more information about the different Items, see port_info/2.
5103
5104 Failure: badarg if Port is not a local port identifier, or an
5105 atom.
5106
5107 erlang:port_info(Port, Item :: connected) ->
5108 {connected, Pid} | undefined
5109
5110 Types:
5111
5112 Port = port() | atom()
5113 Pid = pid()
5114
5115 Pid is the process identifier of the process connected to the
5116 port.
5117
5118 If the port identified by Port is not open, undefined is re‐
5119 turned. If the port is closed and the calling process was previ‐
5120 ously linked to the port, the exit signal from the port is guar‐
5121 anteed to be delivered before port_info/2 returns undefined.
5122
5123 Failure: badarg if Port is not a local port identifier, or an
5124 atom.
5125
5126 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
5127
5128 Types:
5129
5130 Port = port() | atom()
5131 Index = integer() >= 0
5132
5133 Index is the internal index of the port. This index can be used
5134 to separate ports.
5135
5136 If the port identified by Port is not open, undefined is re‐
5137 turned. If the port is closed and the calling process was previ‐
5138 ously linked to the port, the exit signal from the port is guar‐
5139 anteed to be delivered before port_info/2 returns undefined.
5140
5141 Failure: badarg if Port is not a local port identifier, or an
5142 atom.
5143
5144 erlang:port_info(Port, Item :: input) ->
5145 {input, Bytes} | undefined
5146
5147 Types:
5148
5149 Port = port() | atom()
5150 Bytes = integer() >= 0
5151
5152 Bytes is the total number of bytes read from the port.
5153
5154 If the port identified by Port is not open, undefined is re‐
5155 turned. If the port is closed and the calling process was previ‐
5156 ously linked to the port, the exit signal from the port is guar‐
5157 anteed to be delivered before port_info/2 returns undefined.
5158
5159 Failure: badarg if Port is not a local port identifier, or an
5160 atom.
5161
5162 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
5163
5164 Types:
5165
5166 Port = port() | atom()
5167 Pids = [pid()]
5168
5169 Pids is a list of the process identifiers of the processes that
5170 the port is linked to.
5171
5172 If the port identified by Port is not open, undefined is re‐
5173 turned. If the port is closed and the calling process was previ‐
5174 ously linked to the port, the exit signal from the port is guar‐
5175 anteed to be delivered before port_info/2 returns undefined.
5176
5177 Failure: badarg if Port is not a local port identifier, or an
5178 atom.
5179
5180 erlang:port_info(Port, Item :: locking) ->
5181 {locking, Locking} | undefined
5182
5183 Types:
5184
5185 Port = port() | atom()
5186 Locking = false | port_level | driver_level
5187
5188 Locking is one of the following:
5189
5190 * port_level (port-specific locking)
5191
5192 * driver_level (driver-specific locking)
5193
5194 Notice that these results are highly implementation-specific and
5195 can change in a future release.
5196
5197 If the port identified by Port is not open, undefined is re‐
5198 turned. If the port is closed and the calling process was previ‐
5199 ously linked to the port, the exit signal from the port is guar‐
5200 anteed to be delivered before port_info/2 returns undefined.
5201
5202 Failure: badarg if Port is not a local port identifier, or an
5203 atom.
5204
5205 erlang:port_info(Port, Item :: memory) ->
5206 {memory, Bytes} | undefined
5207
5208 Types:
5209
5210 Port = port() | atom()
5211 Bytes = integer() >= 0
5212
5213 Bytes is the total number of bytes allocated for this port by
5214 the runtime system. The port itself can have allocated memory
5215 that is not included in Bytes.
5216
5217 If the port identified by Port is not open, undefined is re‐
5218 turned. If the port is closed and the calling process was previ‐
5219 ously linked to the port, the exit signal from the port is guar‐
5220 anteed to be delivered before port_info/2 returns undefined.
5221
5222 Failure: badarg if Port is not a local port identifier, or an
5223 atom.
5224
5225 erlang:port_info(Port, Item :: monitors) ->
5226 {monitors, Monitors} | undefined
5227
5228 Types:
5229
5230 Port = port() | atom()
5231 Monitors = [{process, pid()}]
5232
5233 Monitors represent processes monitored by this port.
5234
5235 If the port identified by Port is not open, undefined is re‐
5236 turned. If the port is closed and the calling process was previ‐
5237 ously linked to the port, the exit signal from the port is guar‐
5238 anteed to be delivered before port_info/2 returns undefined.
5239
5240 Failure: badarg if Port is not a local port identifier, or an
5241 atom.
5242
5243 erlang:port_info(Port, Item :: monitored_by) ->
5244 {monitored_by, MonitoredBy} | undefined
5245
5246 Types:
5247
5248 Port = port() | atom()
5249 MonitoredBy = [pid()]
5250
5251 Returns list of pids that are monitoring given port at the mo‐
5252 ment.
5253
5254 If the port identified by Port is not open, undefined is re‐
5255 turned. If the port is closed and the calling process was previ‐
5256 ously linked to the port, the exit signal from the port is guar‐
5257 anteed to be delivered before port_info/2 returns undefined.
5258
5259 Failure: badarg if Port is not a local port identifier, or an
5260 atom.
5261
5262 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
5263
5264 Types:
5265
5266 Port = port() | atom()
5267 Name = string()
5268
5269 Name is the command name set by open_port/2.
5270
5271 If the port identified by Port is not open, undefined is re‐
5272 turned. If the port is closed and the calling process was previ‐
5273 ously linked to the port, the exit signal from the port is guar‐
5274 anteed to be delivered before port_info/2 returns undefined.
5275
5276 Failure: badarg if Port is not a local port identifier, or an
5277 atom.
5278
5279 erlang:port_info(Port, Item :: os_pid) ->
5280 {os_pid, OsPid} | undefined
5281
5282 Types:
5283
5284 Port = port() | atom()
5285 OsPid = integer() >= 0 | undefined
5286
5287 OsPid is the process identifier (or equivalent) of an OS process
5288 created with open_port({spawn | spawn_executable, Command}, Op‐
5289 tions). If the port is not the result of spawning an OS process,
5290 the value is undefined.
5291
5292 If the port identified by Port is not open, undefined is re‐
5293 turned. If the port is closed and the calling process was previ‐
5294 ously linked to the port, the exit signal from the port is guar‐
5295 anteed to be delivered before port_info/2 returns undefined.
5296
5297 Failure: badarg if Port is not a local port identifier, or an
5298 atom.
5299
5300 erlang:port_info(Port, Item :: output) ->
5301 {output, Bytes} | undefined
5302
5303 Types:
5304
5305 Port = port() | atom()
5306 Bytes = integer() >= 0
5307
5308 Bytes is the total number of bytes written to the port from Er‐
5309 lang processes using port_command/2, port_command/3, or Port !
5310 {Owner, {command, Data}.
5311
5312 If the port identified by Port is not open, undefined is re‐
5313 turned. If the port is closed and the calling process was previ‐
5314 ously linked to the port, the exit signal from the port is guar‐
5315 anteed to be delivered before port_info/2 returns undefined.
5316
5317 Failure: badarg if Port is not a local port identifier, or an
5318 atom.
5319
5320 erlang:port_info(Port, Item :: parallelism) ->
5321 {parallelism, Boolean} | undefined
5322
5323 Types:
5324
5325 Port = port() | atom()
5326 Boolean = boolean()
5327
5328 Boolean corresponds to the port parallelism hint used by this
5329 port. For more information, see option parallelism of
5330 open_port/2.
5331
5332 erlang:port_info(Port, Item :: queue_size) ->
5333 {queue_size, Bytes} | undefined
5334
5335 Types:
5336
5337 Port = port() | atom()
5338 Bytes = integer() >= 0
5339
5340 Bytes is the total number of bytes queued by the port using the
5341 ERTS driver queue implementation.
5342
5343 If the port identified by Port is not open, undefined is re‐
5344 turned. If the port is closed and the calling process was previ‐
5345 ously linked to the port, the exit signal from the port is guar‐
5346 anteed to be delivered before port_info/2 returns undefined.
5347
5348 Failure: badarg if Port is not a local port identifier, or an
5349 atom.
5350
5351 erlang:port_info(Port, Item :: registered_name) ->
5352 {registered_name, RegisteredName} |
5353 [] | undefined
5354
5355 Types:
5356
5357 Port = port() | atom()
5358 RegisteredName = atom()
5359
5360 RegisteredName is the registered name of the port. If the port
5361 has no registered name, [] is returned.
5362
5363 If the port identified by Port is not open, undefined is re‐
5364 turned. If the port is closed and the calling process was previ‐
5365 ously linked to the port, the exit signal from the port is guar‐
5366 anteed to be delivered before port_info/2 returns undefined.
5367
5368 Failure: badarg if Port is not a local port identifier, or an
5369 atom.
5370
5371 port_to_list(Port) -> string()
5372
5373 Types:
5374
5375 Port = port()
5376
5377 Returns a string corresponding to the text representation of the
5378 port identifier Port.
5379
5380 erlang:ports() -> [port()]
5381
5382 Returns a list of port identifiers corresponding to all the
5383 ports existing on the local node.
5384
5385 Notice that an exiting port exists, but is not open.
5386
5387 pre_loaded() -> [module()]
5388
5389 Returns a list of Erlang modules that are preloaded in the run-
5390 time system. Pre-loaded modules are Erlang modules that are
5391 needed to bootstrap the system to load the first Erlang modules
5392 from either disk or by using erl_boot_server.
5393
5394 erlang:process_display(Pid, Type) -> true
5395
5396 Types:
5397
5398 Pid = pid()
5399 Type = backtrace
5400
5401 Writes information about the local process Pid on standard er‐
5402 ror. The only allowed value for the atom Type is backtrace,
5403 which shows the contents of the call stack, including informa‐
5404 tion about the call chain, with the current function printed
5405 first. The format of the output is not further defined.
5406
5407 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
5408
5409 Types:
5410
5411 Boolean = OldBoolean = boolean()
5412
5413 When trap_exit is set to true, exit signals arriving to a
5414 process are converted to {'EXIT', From, Reason} messages, which
5415 can be received as ordinary messages. If trap_exit is set to
5416 false, the process exits if it receives an exit signal other
5417 than normal and the exit signal is propagated to its linked pro‐
5418 cesses. Application processes are normally not to trap exits.
5419
5420 Returns the old value of the flag.
5421
5422 See also exit/2.
5423
5424 process_flag(Flag :: error_handler, Module) -> OldModule
5425
5426 Types:
5427
5428 Module = OldModule = atom()
5429
5430 Used by a process to redefine the error handler for undefined
5431 function calls and undefined registered processes. Inexperienced
5432 users are not to use this flag, as code auto-loading depends on
5433 the correct operation of the error handling module.
5434
5435 Returns the old value of the flag.
5436
5437 process_flag(Flag :: fullsweep_after, FullsweepAfter) ->
5438 OldFullsweepAfter
5439
5440 Types:
5441
5442 FullsweepAfter = OldFullsweepAfter = integer() >= 0
5443
5444 Changes the maximum number of generational collections before
5445 forcing a fullsweep for the calling process.
5446
5447 Returns the old value of the flag.
5448
5449 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
5450
5451 Types:
5452
5453 MinHeapSize = OldMinHeapSize = integer() >= 0
5454
5455 Changes the minimum heap size for the calling process.
5456
5457 Returns the old value of the flag.
5458
5459 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
5460 OldMinBinVHeapSize
5461
5462 Types:
5463
5464 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
5465
5466 Changes the minimum binary virtual heap size for the calling
5467 process.
5468
5469 Returns the old value of the flag.
5470
5471 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
5472
5473 Types:
5474
5475 MaxHeapSize = OldMaxHeapSize = max_heap_size()
5476 max_heap_size() =
5477 integer() >= 0 |
5478 #{size => integer() >= 0,
5479 kill => boolean(),
5480 error_logger => boolean()}
5481
5482 This flag sets the maximum heap size for the calling process. If
5483 MaxHeapSize is an integer, the system default values for kill
5484 and error_logger are used.
5485
5486 size:
5487 The maximum size in words of the process. If set to zero,
5488 the heap size limit is disabled. badarg is be thrown if the
5489 value is smaller than min_heap_size. The size check is only
5490 done when a garbage collection is triggered.
5491
5492 size is the entire heap of the process when garbage collec‐
5493 tion is triggered. This includes all generational heaps, the
5494 process stack, any messages that are considered to be part
5495 of the heap, and any extra memory that the garbage collector
5496 needs during collection.
5497
5498 size is the same as can be retrieved using er‐
5499 lang:process_info(Pid, total_heap_size), or by adding
5500 heap_block_size, old_heap_block_size and mbuf_size from er‐
5501 lang:process_info(Pid, garbage_collection_info).
5502
5503 kill:
5504 When set to true, the runtime system sends an untrappable
5505 exit signal with reason kill to the process if the maximum
5506 heap size is reached. The garbage collection that triggered
5507 the kill is not completed, instead the process exits as soon
5508 as possible. When set to false, no exit signal is sent to
5509 the process, instead it continues executing.
5510
5511 If kill is not defined in the map, the system default will
5512 be used. The default system default is true. It can be
5513 changed by either option +hmaxk in erl(1), or erlang:sys‐
5514 tem_flag(max_heap_size, MaxHeapSize).
5515
5516 error_logger:
5517 When set to true, the runtime system logs an error event via
5518 logger, containing details about the process when the maxi‐
5519 mum heap size is reached. One log event is sent each time
5520 the limit is reached.
5521
5522 If error_logger is not defined in the map, the system de‐
5523 fault is used. The default system default is true. It can be
5524 changed by either the option +hmaxel int erl(1), or er‐
5525 lang:system_flag(max_heap_size, MaxHeapSize).
5526
5527 The heap size of a process is quite hard to predict, especially
5528 the amount of memory that is used during the garbage collection.
5529 When contemplating using this option, it is recommended to first
5530 run it in production with kill set to false and inspect the log
5531 events to see what the normal peak sizes of the processes in the
5532 system is and then tune the value accordingly.
5533
5534 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
5535
5536 Types:
5537
5538 MQD = OldMQD = message_queue_data()
5539 message_queue_data() = off_heap | on_heap
5540
5541 Determines how messages in the message queue are stored, as fol‐
5542 lows:
5543
5544 off_heap:
5545 All messages in the message queue will be stored outside the
5546 process heap. This implies that no messages in the message
5547 queue will be part of a garbage collection of the process.
5548
5549 on_heap:
5550 All messages in the message queue will eventually be placed
5551 on the process heap. They can, however, be temporarily
5552 stored off the heap. This is how messages have always been
5553 stored up until ERTS 8.0.
5554
5555 The default value of the message_queue_data process flag is de‐
5556 termined by the command-line argument +hmqd in erl(1).
5557
5558 If the process may potentially accumulate a large number of mes‐
5559 sages in its queue it is recommended to set the flag value to
5560 off_heap. This is due to the fact that the garbage collection of
5561 a process that has a large number of messages stored on the heap
5562 can become extremely expensive and the process can consume large
5563 amounts of memory. The performance of the actual message passing
5564 is, however, generally better when the flag value is on_heap.
5565
5566 Changing the flag value causes any existing messages to be
5567 moved. The move operation is initiated, but not necessarily com‐
5568 pleted, by the time the function returns.
5569
5570 Returns the old value of the flag.
5571
5572 process_flag(Flag :: priority, Level) -> OldLevel
5573
5574 Types:
5575
5576 Level = OldLevel = priority_level()
5577 priority_level() = low | normal | high | max
5578
5579 Sets the process priority. Level is an atom. Four priority lev‐
5580 els exist: low, normal, high, and max. Default is normal.
5581
5582 Note:
5583 Priority level max is reserved for internal use in the Erlang
5584 runtime system, and is not to be used by others.
5585
5586
5587 Internally in each priority level, processes are scheduled in a
5588 round robin fashion.
5589
5590 Execution of processes on priority normal and low are inter‐
5591 leaved. Processes on priority low are selected for execution
5592 less frequently than processes on priority normal.
5593
5594 When runnable processes on priority high exist, no processes on
5595 priority low or normal are selected for execution. Notice how‐
5596 ever that this does not mean that no processes on priority low
5597 or normal can run when processes are running on priority high.
5598 When using multiple schedulers, more processes can be running in
5599 parallel than processes on priority high. That is, a low and a
5600 high priority process can execute at the same time.
5601
5602 When runnable processes on priority max exist, no processes on
5603 priority low, normal, or high are selected for execution. As
5604 with priority high, processes on lower priorities can execute in
5605 parallel with processes on priority max.
5606
5607 Scheduling is pre-emptive. Regardless of priority, a process is
5608 pre-empted when it has consumed more than a certain number of
5609 reductions since the last time it was selected for execution.
5610
5611 Note:
5612 Do not depend on the scheduling to remain exactly as it is to‐
5613 day. Scheduling is likely to be changed in a future release to
5614 use available processor cores better.
5615
5616
5617 There is no automatic mechanism for avoiding priority inversion,
5618 such as priority inheritance or priority ceilings. When using
5619 priorities, take this into account and handle such scenarios by
5620 yourself.
5621
5622 Making calls from a high priority process into code that you has
5623 no control over can cause the high priority process to wait for
5624 a process with lower priority. That is, effectively decreasing
5625 the priority of the high priority process during the call. Even
5626 if this is not the case with one version of the code that you
5627 have no control over, it can be the case in a future version of
5628 it. This can, for example, occur if a high priority process
5629 triggers code loading, as the code server runs on priority nor‐
5630 mal.
5631
5632 Other priorities than normal are normally not needed. When other
5633 priorities are used, use them with care, especially priority
5634 high. A process on priority high is only to perform work for
5635 short periods. Busy looping for long periods in a high priority
5636 process causes most likely problems, as important OTP servers
5637 run on priority normal.
5638
5639 Returns the old value of the flag.
5640
5641 process_flag(Flag :: save_calls, N) -> OldN
5642
5643 Types:
5644
5645 N = OldN = 0..10000
5646
5647 N must be an integer in the interval 0..10000. If N > 0, call
5648 saving is made active for the process. This means that informa‐
5649 tion about the N most recent global function calls, BIF calls,
5650 sends, and receives made by the process are saved in a list,
5651 which can be retrieved with process_info(Pid, last_calls). A
5652 global function call is one in which the module of the function
5653 is explicitly mentioned. Only a fixed amount of information is
5654 saved, as follows:
5655
5656 * A tuple {Module, Function, Arity} for function calls
5657
5658 * The atoms send, 'receive', and timeout for sends and re‐
5659 ceives ('receive' when a message is received and timeout
5660 when a receive times out)
5661
5662 If N = 0, call saving is disabled for the process, which is the
5663 default. Whenever the size of the call saving list is set, its
5664 contents are reset.
5665
5666 Returns the old value of the flag.
5667
5668 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
5669
5670 Types:
5671
5672 Boolean = OldBoolean = boolean()
5673
5674 Sets or clears flag sensitive for the current process. When a
5675 process has been marked as sensitive by calling
5676 process_flag(sensitive, true), features in the runtime system
5677 that can be used for examining the data or inner working of the
5678 process are silently disabled.
5679
5680 Features that are disabled include (but are not limited to) the
5681 following:
5682
5683 * Tracing. Trace flags can still be set for the process, but
5684 no trace messages of any kind are generated. (If flag sensi‐
5685 tive is turned off, trace messages are again generated if
5686 any trace flags are set.)
5687
5688 * Sequential tracing. The sequential trace token is propagated
5689 as usual, but no sequential trace messages are generated.
5690
5691 process_info/1,2 cannot be used to read out the message queue or
5692 the process dictionary (both are returned as empty lists).
5693
5694 Stack back-traces cannot be displayed for the process.
5695
5696 In crash dumps, the stack, messages, and the process dictionary
5697 are omitted.
5698
5699 If {save_calls,N} has been set for the process, no function
5700 calls are saved to the call saving list. (The call saving list
5701 is not cleared. Also, send, receive, and time-out events are
5702 still added to the list.)
5703
5704 Returns the old value of the flag.
5705
5706 process_flag(Pid, Flag, Value) -> OldValue
5707
5708 Types:
5709
5710 Pid = pid()
5711 Flag = save_calls
5712 Value = OldValue = integer() >= 0
5713
5714 Sets certain flags for the process Pid, in the same manner as
5715 process_flag/2. Returns the old value of the flag. The valid
5716 values for Flag are only a subset of those allowed in
5717 process_flag/2, namely save_calls.
5718
5719 Failure: badarg if Pid is not a local process.
5720
5721 process_info(Pid) -> Info
5722
5723 Types:
5724
5725 Pid = pid()
5726 Info = [InfoTuple] | undefined
5727 InfoTuple = process_info_result_item()
5728 process_info_result_item() =
5729 {backtrace, Bin :: binary()} |
5730 {binary,
5731 BinInfo ::
5732 [{integer() >= 0,
5733 integer() >= 0,
5734 integer() >= 0}]} |
5735 {catchlevel, CatchLevel :: integer() >= 0} |
5736 {current_function,
5737 {Module :: module(), Function :: atom(), Arity :: arity()} |
5738 undefined} |
5739 {current_location,
5740 {Module :: module(),
5741 Function :: atom(),
5742 Arity :: arity(),
5743 Location ::
5744 [{file, Filename :: string()} |
5745 {line, Line :: integer() >= 1}]}} |
5746 {current_stacktrace, Stack :: [stack_item()]} |
5747 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5748 {error_handler, Module :: module()} |
5749 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5750 {garbage_collection_info,
5751 GCInfo :: [{atom(), integer() >= 0}]} |
5752 {group_leader, GroupLeader :: pid()} |
5753 {heap_size, Size :: integer() >= 0} |
5754 {initial_call, mfa()} |
5755 {links, PidsAndPorts :: [pid() | port()]} |
5756 {last_calls, false | (Calls :: [mfa()])} |
5757 {memory, Size :: integer() >= 0} |
5758 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5759 {messages, MessageQueue :: [term()]} |
5760 {min_heap_size, MinHeapSize :: integer() >= 0} |
5761 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5762 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5763 {monitored_by,
5764 MonitoredBy :: [pid() | port() | nif_resource()]} |
5765 {monitors,
5766 Monitors ::
5767 [{process | port,
5768 Pid ::
5769 pid() |
5770 port() |
5771 {RegName :: atom(), Node :: node()}}]} |
5772 {message_queue_data, MQD :: message_queue_data()} |
5773 {priority, Level :: priority_level()} |
5774 {reductions, Number :: integer() >= 0} |
5775 {registered_name, [] | (Atom :: atom())} |
5776 {sequential_trace_token,
5777 [] | (SequentialTraceToken :: term())} |
5778 {stack_size, Size :: integer() >= 0} |
5779 {status,
5780 Status ::
5781 exiting | garbage_collecting | waiting | running |
5782 runnable | suspended} |
5783 {suspending,
5784 SuspendeeList ::
5785 [{Suspendee :: pid(),
5786 ActiveSuspendCount :: integer() >= 0,
5787 OutstandingSuspendCount :: integer() >= 0}]} |
5788 {total_heap_size, Size :: integer() >= 0} |
5789 {trace, InternalTraceFlags :: integer() >= 0} |
5790 {trap_exit, Boolean :: boolean()}
5791 priority_level() = low | normal | high | max
5792 stack_item() =
5793 {Module :: module(),
5794 Function :: atom(),
5795 Arity :: arity() | (Args :: [term()]),
5796 Location ::
5797 [{file, Filename :: string()} |
5798 {line, Line :: integer() >= 1}]}
5799 max_heap_size() =
5800 integer() >= 0 |
5801 #{size => integer() >= 0,
5802 kill => boolean(),
5803 error_logger => boolean()}
5804 message_queue_data() = off_heap | on_heap
5805
5806 Returns a list containing InfoTuples with miscellaneous informa‐
5807 tion about the process identified by Pid, or undefined if the
5808 process is not alive.
5809
5810 The order of the InfoTuples is undefined and all InfoTuples are
5811 not mandatory. The InfoTuples part of the result can be changed
5812 without prior notice.
5813
5814 The InfoTuples with the following items are part of the result:
5815
5816 * current_function
5817
5818 * initial_call
5819
5820 * status
5821
5822 * message_queue_len
5823
5824 * links
5825
5826 * dictionary
5827
5828 * trap_exit
5829
5830 * error_handler
5831
5832 * priority
5833
5834 * group_leader
5835
5836 * total_heap_size
5837
5838 * heap_size
5839
5840 * stack_size
5841
5842 * reductions
5843
5844 * garbage_collection
5845
5846 If the process identified by Pid has a registered name, also an
5847 InfoTuple with item registered_name is included.
5848
5849 For information about specific InfoTuples, see process_info/2.
5850
5851 Warning:
5852 This BIF is intended for debugging only. For all other purposes,
5853 use process_info/2.
5854
5855
5856 Failure: badarg if Pid is not a local process.
5857
5858 process_info(Pid, Item) -> InfoTuple | [] | undefined
5859
5860 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5861
5862 Types:
5863
5864 Pid = pid()
5865 ItemList = [Item]
5866 Item = process_info_item()
5867 InfoTupleList = [InfoTuple]
5868 InfoTuple = process_info_result_item()
5869 process_info_item() =
5870 backtrace | binary | catchlevel | current_function |
5871 current_location | current_stacktrace | dictionary |
5872 error_handler | garbage_collection | garbage_collection_info |
5873 group_leader | heap_size | initial_call | links | last_calls |
5874 memory | message_queue_len | messages | min_heap_size |
5875 min_bin_vheap_size | monitored_by | monitors |
5876 message_queue_data | priority | reductions | registered_name |
5877 sequential_trace_token | stack_size | status | suspending |
5878 total_heap_size | trace | trap_exit
5879 process_info_result_item() =
5880 {backtrace, Bin :: binary()} |
5881 {binary,
5882 BinInfo ::
5883 [{integer() >= 0,
5884 integer() >= 0,
5885 integer() >= 0}]} |
5886 {catchlevel, CatchLevel :: integer() >= 0} |
5887 {current_function,
5888 {Module :: module(), Function :: atom(), Arity :: arity()} |
5889 undefined} |
5890 {current_location,
5891 {Module :: module(),
5892 Function :: atom(),
5893 Arity :: arity(),
5894 Location ::
5895 [{file, Filename :: string()} |
5896 {line, Line :: integer() >= 1}]}} |
5897 {current_stacktrace, Stack :: [stack_item()]} |
5898 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5899 {error_handler, Module :: module()} |
5900 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5901 {garbage_collection_info,
5902 GCInfo :: [{atom(), integer() >= 0}]} |
5903 {group_leader, GroupLeader :: pid()} |
5904 {heap_size, Size :: integer() >= 0} |
5905 {initial_call, mfa()} |
5906 {links, PidsAndPorts :: [pid() | port()]} |
5907 {last_calls, false | (Calls :: [mfa()])} |
5908 {memory, Size :: integer() >= 0} |
5909 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5910 {messages, MessageQueue :: [term()]} |
5911 {min_heap_size, MinHeapSize :: integer() >= 0} |
5912 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5913 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5914 {monitored_by,
5915 MonitoredBy :: [pid() | port() | nif_resource()]} |
5916 {monitors,
5917 Monitors ::
5918 [{process | port,
5919 Pid ::
5920 pid() |
5921 port() |
5922 {RegName :: atom(), Node :: node()}}]} |
5923 {message_queue_data, MQD :: message_queue_data()} |
5924 {priority, Level :: priority_level()} |
5925 {reductions, Number :: integer() >= 0} |
5926 {registered_name, [] | (Atom :: atom())} |
5927 {sequential_trace_token,
5928 [] | (SequentialTraceToken :: term())} |
5929 {stack_size, Size :: integer() >= 0} |
5930 {status,
5931 Status ::
5932 exiting | garbage_collecting | waiting | running |
5933 runnable | suspended} |
5934 {suspending,
5935 SuspendeeList ::
5936 [{Suspendee :: pid(),
5937 ActiveSuspendCount :: integer() >= 0,
5938 OutstandingSuspendCount :: integer() >= 0}]} |
5939 {total_heap_size, Size :: integer() >= 0} |
5940 {trace, InternalTraceFlags :: integer() >= 0} |
5941 {trap_exit, Boolean :: boolean()}
5942 stack_item() =
5943 {Module :: module(),
5944 Function :: atom(),
5945 Arity :: arity() | (Args :: [term()]),
5946 Location ::
5947 [{file, Filename :: string()} |
5948 {line, Line :: integer() >= 1}]}
5949 priority_level() = low | normal | high | max
5950 max_heap_size() =
5951 integer() >= 0 |
5952 #{size => integer() >= 0,
5953 kill => boolean(),
5954 error_logger => boolean()}
5955 message_queue_data() = off_heap | on_heap
5956
5957 Returns information about the process identified by Pid, as
5958 specified by Item or ItemList. Returns undefined if the process
5959 is not alive.
5960
5961 If the process is alive and a single Item is specified, the re‐
5962 turned value is the corresponding InfoTuple, unless Item =:=
5963 registered_name and the process has no registered name. In this
5964 case, [] is returned. This strange behavior is because of his‐
5965 torical reasons, and is kept for backward compatibility.
5966
5967 If ItemList is specified, the result is InfoTupleList. The Info‐
5968 Tuples in InfoTupleList are included with the corresponding
5969 Items in the same order as the Items were included in ItemList.
5970 Valid Items can be included multiple times in ItemList.
5971
5972 Getting process informations follows the signal ordering guaran‐
5973 tees described in the Processes Chapter in the Erlang Reference
5974 Manual .
5975
5976 Note:
5977 If registered_name is part of ItemList and the process has no
5978 name registered, a {registered_name, []}, InfoTuple will be in‐
5979 cluded in the resulting InfoTupleList. This behavior is differ‐
5980 ent when a single Item =:= registered_name is specified, and
5981 when process_info/1 is used.
5982
5983
5984 Valid InfoTuples with corresponding Items:
5985
5986 {backtrace, Bin}:
5987 Binary Bin contains the same information as the output from
5988 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5989 to obtain the string of characters from the binary.
5990
5991 {binary, BinInfo}:
5992 BinInfo is a list containing miscellaneous information about
5993 binaries on the heap of this process. This InfoTuple can be
5994 changed or removed without prior notice. In the current im‐
5995 plementation BinInfo is a list of tuples. The tuples con‐
5996 tain; BinaryId, BinarySize, BinaryRefcCount.
5997
5998 Depending on the value of the message_queue_data process
5999 flag the message queue may be stored on the heap.
6000
6001 {catchlevel, CatchLevel}:
6002 CatchLevel is the number of currently active catches in this
6003 process. This InfoTuple can be changed or removed without
6004 prior notice.
6005
6006 {current_function, {Module, Function, Arity} | undefined}:
6007 Module, Function, Arity is the current function call of the
6008 process. The value undefined can be returned if the process
6009 is currently executing native compiled code.
6010
6011 {current_location, {Module, Function, Arity, Location}}:
6012 Module, Function, Arity is the current function call of the
6013 process. Location is a list of two-tuples describing the lo‐
6014 cation in the source code.
6015
6016 {current_stacktrace, Stack}:
6017 Returns the current call stack back-trace (stacktrace) of
6018 the process. The stack has the same format as in the catch
6019 part of a try. See The call-stack back trace (stacktrace).
6020 The depth of the stacktrace is truncated according to the
6021 backtrace_depth system flag setting.
6022
6023 {dictionary, Dictionary}:
6024 Dictionary is the process dictionary.
6025
6026 {error_handler, Module}:
6027 Module is the error handler module used by the process (for
6028 undefined function calls, for example).
6029
6030 {garbage_collection, GCInfo}:
6031 GCInfo is a list containing miscellaneous information about
6032 garbage collection for this process. The content of GCInfo
6033 can be changed without prior notice.
6034
6035 {garbage_collection_info, GCInfo}:
6036 GCInfo is a list containing miscellaneous detailed informa‐
6037 tion about garbage collection for this process. The content
6038 of GCInfo can be changed without prior notice. For details
6039 about the meaning of each item, see gc_minor_start in er‐
6040 lang:trace/3.
6041
6042 {group_leader, GroupLeader}:
6043 GroupLeader is the group leader for the I/O of the process.
6044
6045 {heap_size, Size}:
6046 Size is the size in words of the youngest heap generation of
6047 the process. This generation includes the process stack.
6048 This information is highly implementation-dependent, and can
6049 change if the implementation changes.
6050
6051 {initial_call, {Module, Function, Arity}}:
6052 Module, Function, Arity is the initial function call with
6053 which the process was spawned.
6054
6055 {links, PidsAndPorts}:
6056 PidsAndPorts is a list of process identifiers and port iden‐
6057 tifiers, with processes or ports to which the process has a
6058 link.
6059
6060 {last_calls, false|Calls}:
6061 The value is false if call saving is not active for the
6062 process (see process_flag/3). If call saving is active, a
6063 list is returned, in which the last element is the most re‐
6064 cent called.
6065
6066 {memory, Size}:
6067
6068
6069 Size is the size in bytes of the process. This includes call
6070 stack, heap, and internal structures.
6071
6072 {message_queue_len, MessageQueueLen}:
6073 MessageQueueLen is the number of messages currently in the
6074 message queue of the process. This is the length of the list
6075 MessageQueue returned as the information item messages (see
6076 below).
6077
6078 {messages, MessageQueue}:
6079 MessageQueue is a list of the messages to the process, which
6080 have not yet been processed.
6081
6082 {min_heap_size, MinHeapSize}:
6083 MinHeapSize is the minimum heap size for the process.
6084
6085 {min_bin_vheap_size, MinBinVHeapSize}:
6086 MinBinVHeapSize is the minimum binary virtual heap size for
6087 the process.
6088
6089 {monitored_by, MonitoredBy}:
6090 A list of identifiers for all the processes, ports and NIF
6091 resources, that are monitoring the process.
6092
6093 {monitors, Monitors}:
6094 A list of monitors (started by monitor/2) that are active
6095 for the process. For a local process monitor or a remote
6096 process monitor by a process identifier, the list consists
6097 of:
6098
6099 {process, Pid}:
6100 Process is monitored by pid.
6101
6102 {process, {RegName, Node}}:
6103 Local or remote process is monitored by name.
6104
6105 {port, PortId}:
6106 Local port is monitored by port id.
6107
6108 {port, {RegName, Node}}:
6109 Local port is monitored by name. Please note, that remote
6110 port monitors are not supported, so Node will always be
6111 the local node name.
6112
6113 {message_queue_data, MQD}:
6114 MQD is the current value of the message_queue_data process
6115 flag, which can be either off_heap or on_heap. For more in‐
6116 formation, see the documentation of process_flag(mes‐
6117 sage_queue_data, MQD).
6118
6119 {priority, Level}:
6120 Level is the current priority level for the process. For
6121 more information on priorities, see process_flag(priority,
6122 Level).
6123
6124 {reductions, Number}:
6125 Number is the number of reductions executed by the process.
6126
6127 {registered_name, Atom}:
6128 Atom is the registered process name. If the process has no
6129 registered name, this tuple is not present in the list.
6130
6131 {sequential_trace_token, [] | SequentialTraceToken}:
6132 SequentialTraceToken is the sequential trace token for the
6133 process. This InfoTuple can be changed or removed without
6134 prior notice.
6135
6136 {stack_size, Size}:
6137 Size is the stack size, in words, of the process.
6138
6139 {status, Status}:
6140 Status is the status of the process and is one of the fol‐
6141 lowing:
6142
6143 * exiting
6144
6145 * garbage_collecting
6146
6147 * waiting (for a message)
6148
6149 * running
6150
6151 * runnable (ready to run, but another process is running)
6152
6153 * suspended (suspended on a "busy" port or by the BIF er‐
6154 lang:suspend_process/1,2)
6155
6156 {suspending, SuspendeeList}:
6157 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
6158 OutstandingSuspendCount} tuples. Suspendee is the process
6159 identifier of a process that has been, or is to be, sus‐
6160 pended by the process identified by Pid through the BIF er‐
6161 lang:suspend_process/2 or erlang:suspend_process/1.
6162
6163 ActiveSuspendCount is the number of times Suspendee has been
6164 suspended by Pid. OutstandingSuspendCount is the number of
6165 not yet completed suspend requests sent by Pid, that is:
6166
6167 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
6168 suspended state.
6169
6170 * If OutstandingSuspendCount =/= 0, option asynchronous of
6171 erlang:suspend_process/2 has been used and the suspendee
6172 has not yet been suspended by Pid.
6173
6174 Notice that ActiveSuspendCount and OutstandingSuspendCount
6175 are not the total suspend count on Suspendee, only the parts
6176 contributed by Pid.
6177
6178 {total_heap_size, Size}:
6179 Size is the total size, in words, of all heap fragments of
6180 the process. This includes the process stack and any unre‐
6181 ceived messages that are considered to be part of the heap.
6182
6183 {trace, InternalTraceFlags}:
6184 InternalTraceFlags is an integer representing the internal
6185 trace flag for this process. This InfoTuple can be changed
6186 or removed without prior notice.
6187
6188 {trap_exit, Boolean}:
6189 Boolean is true if the process is trapping exits, otherwise
6190 false.
6191
6192 Notice that not all implementations support all these Items.
6193
6194 Failures:
6195
6196 badarg:
6197 If Pid is not a local process.
6198
6199 badarg:
6200 If Item is an invalid item.
6201
6202 processes() -> [pid()]
6203
6204 Returns a list of process identifiers corresponding to all the
6205 processes currently existing on the local node.
6206
6207 Notice that an exiting process exists, but is not alive. That
6208 is, is_process_alive/1 returns false for an exiting process, but
6209 its process identifier is part of the result returned from pro‐
6210 cesses/0.
6211
6212 Example:
6213
6214 > processes().
6215 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
6216
6217 purge_module(Module) -> true
6218
6219 Types:
6220
6221 Module = atom()
6222
6223 Removes old code for Module. Before this BIF is used,
6224 check_process_code/2 is to be called to check that no processes
6225 execute old code in the module.
6226
6227 Warning:
6228 This BIF is intended for the code server (see code(3)) and is
6229 not to be used elsewhere.
6230
6231
6232 Note:
6233 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
6234 still execute the old code is killed by this function. In ear‐
6235 lier versions, such incorrect use could cause much more fatal
6236 failures, like emulator crash.
6237
6238
6239 Failure: badarg if there is no old code for Module.
6240
6241 put(Key, Val) -> term()
6242
6243 Types:
6244
6245 Key = Val = term()
6246
6247 Adds a new Key to the process dictionary, associated with the
6248 value Val, and returns undefined. If Key exists, the old value
6249 is deleted and replaced by Val, and the function returns the old
6250 value. The average time complexity for the current implementa‐
6251 tion of this function is O(1) and the worst case time complexity
6252 is O(N), where N is the number of items in the process dictio‐
6253 nary. Example:
6254
6255 > X = put(name, walrus), Y = put(name, carpenter),
6256 Z = get(name),
6257 {X, Y, Z}.
6258 {undefined,walrus,carpenter}
6259
6260 Note:
6261 The values stored when put is evaluated within the scope of a
6262 catch are not retracted if a throw is evaluated, or if an error
6263 occurs.
6264
6265
6266 erlang:raise(Class, Reason, Stacktrace) -> badarg
6267
6268 Types:
6269
6270 Class = error | exit | throw
6271 Reason = term()
6272 Stacktrace = raise_stacktrace() | stacktrace()
6273 raise_stacktrace() =
6274 [{module(), atom(), arity() | [term()]} |
6275 {function(), arity() | [term()]}]
6276
6277 Raises an exception of the specified class, reason, and call
6278 stack backtrace (stacktrace).
6279
6280 Class is error, exit, or throw. So, if it were not for the
6281 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
6282 lent to erlang:Class(Reason) (given that Class is a valid
6283 class).
6284
6285 Reason can be any term.
6286
6287 Stacktrace is a list as provided in a try-catch clause.
6288
6289 try
6290 ...
6291 catch Class:Reason:Stacktrace ->
6292 ...
6293 end
6294
6295 That is, a list of four-tuples {Module, Function, Arity | Args,
6296 ExtraInfo}, where Module and Function are atoms, and the third
6297 element is an integer arity or an argument list. The stacktrace
6298 can also contain {Fun, Args, ExtraInfo} tuples, where Fun is a
6299 local fun and Args is an argument list.
6300
6301 Element ExtraInfo at the end is optional. Omitting it is equiva‐
6302 lent to specifying an empty list.
6303
6304 The stacktrace is used as the exception stacktrace for the call‐
6305 ing process; it is truncated to the current maximum stacktrace
6306 depth.
6307
6308 As evaluating this function causes the process to terminate, it
6309 has no return value unless the arguments are invalid, in which
6310 case the function returns the error reason badarg. If you want
6311 to be sure not to return, you can call error(erlang:raise(Class,
6312 Reason, Stacktrace)) and hope to distinguish exceptions later.
6313
6314 See the reference manual about errors and error handling for
6315 more information about exception classes and how to catch excep‐
6316 tions.
6317
6318 erlang:read_timer(TimerRef) -> Result
6319
6320 Types:
6321
6322 TimerRef = reference()
6323 Time = integer() >= 0
6324 Result = Time | false
6325
6326 Reads the state of a timer. The same as calling er‐
6327 lang:read_timer(TimerRef, []).
6328
6329 erlang:read_timer(TimerRef, Options) -> Result | ok
6330
6331 Types:
6332
6333 TimerRef = reference()
6334 Async = boolean()
6335 Option = {async, Async}
6336 Options = [Option]
6337 Time = integer() >= 0
6338 Result = Time | false
6339
6340 Reads the state of a timer that has been created by either er‐
6341 lang:start_timer or erlang:send_after. TimerRef identifies the
6342 timer, and was returned by the BIF that created the timer.
6343
6344 Options:
6345
6346 {async, Async}:
6347 Asynchronous request for state information. Async defaults
6348 to false, which causes the operation to be performed syn‐
6349 chronously. In this case, the Result is returned by er‐
6350 lang:read_timer. When Async is true, erlang:read_timer sends
6351 an asynchronous request for the state information to the
6352 timer service that manages the timer, and then returns ok. A
6353 message on the format {read_timer, TimerRef, Result} is sent
6354 to the caller of erlang:read_timer when the operation has
6355 been processed.
6356
6357 More Options can be added in the future.
6358
6359 If Result is an integer, it represents the time in milliseconds
6360 left until the timer expires.
6361
6362 If Result is false, a timer corresponding to TimerRef could not
6363 be found. This because the timer had expired, or been canceled,
6364 or because TimerRef never has corresponded to a timer. Even if
6365 the timer has expired, it does not tell you whether or not the
6366 time-out message has arrived at its destination yet.
6367
6368 Note:
6369 The timer service that manages the timer can be co-located with
6370 another scheduler than the scheduler that the calling process is
6371 executing on. If so, communication with the timer service takes
6372 much longer time than if it is located locally. If the calling
6373 process is in a critical path, and can do other things while
6374 waiting for the result of this operation, you want to use option
6375 {async, true}. If using option {async, false}, the calling
6376 process is blocked until the operation has been performed.
6377
6378
6379 See also erlang:send_after/4, erlang:start_timer/4, and er‐
6380 lang:cancel_timer/2.
6381
6382 ref_to_list(Ref) -> string()
6383
6384 Types:
6385
6386 Ref = reference()
6387
6388 Returns a string corresponding to the text representation of
6389 Ref.
6390
6391 Warning:
6392 This BIF is intended for debugging and is not to be used in ap‐
6393 plication programs.
6394
6395
6396 register(RegName, PidOrPort) -> true
6397
6398 Types:
6399
6400 RegName = atom()
6401 PidOrPort = port() | pid()
6402
6403 Registers the name RegName with a process identifier (pid) or a
6404 port identifier in the name registry. RegName, which must be an
6405 atom, can be used instead of the pid or port identifier in send
6406 operator (RegName ! Message) and most other BIFs that take a pid
6407 or port identifies as an argument. Example:
6408
6409 > register(db, Pid).
6410 true
6411
6412 The registered name is considered a Directly Visible Erlang Re‐
6413 source and is automatically unregistered when the process termi‐
6414 nates.
6415
6416 Failures:
6417
6418 badarg:
6419 If PidOrPort is not an existing local process or port.
6420
6421 badarg:
6422 If RegName is already in use.
6423
6424 badarg:
6425 If the process or port is already registered (already has a
6426 name).
6427
6428 badarg:
6429 If RegName is the atom undefined.
6430
6431 registered() -> [RegName]
6432
6433 Types:
6434
6435 RegName = atom()
6436
6437 Returns a list of names that have been registered using regis‐
6438 ter/2, for example:
6439
6440 > registered().
6441 [code_server, file_server, init, user, my_db]
6442
6443 erlang:resume_process(Suspendee) -> true
6444
6445 Types:
6446
6447 Suspendee = pid()
6448
6449 Decreases the suspend count on the process identified by Sus‐
6450 pendee. Suspendee is previously to have been suspended through
6451 erlang:suspend_process/2 or erlang:suspend_process/1 by the
6452 process calling erlang:resume_process(Suspendee). When the sus‐
6453 pend count on Suspendee reaches zero, Suspendee is resumed, that
6454 is, its state is changed from suspended into the state it had
6455 before it was suspended.
6456
6457 Warning:
6458 This BIF is intended for debugging only.
6459
6460
6461 Failures:
6462
6463 badarg:
6464 If Suspendee is not a process identifier.
6465
6466 badarg:
6467 If the process calling erlang:resume_process/1 had not pre‐
6468 viously increased the suspend count on the process identi‐
6469 fied by Suspendee.
6470
6471 badarg:
6472 If the process identified by Suspendee is not alive.
6473
6474 round(Number) -> integer()
6475
6476 Types:
6477
6478 Number = number()
6479
6480 Returns an integer by rounding Number, for example:
6481
6482 round(42.1).
6483 42
6484
6485 round(5.5).
6486 6
6487
6488 round(-5.5).
6489 -6
6490
6491 round(36028797018963969.0).
6492 36028797018963968
6493
6494 In the last example, round(36028797018963969.0) evaluates to
6495 36028797018963968. The reason for this is that the number
6496 36028797018963969.0 cannot be represented exactly as a float
6497 value. Instead, the float literal is represented as
6498 36028797018963968.0, which is the closest number that can be
6499 represented exactly as a float value. See Representation of
6500 Floating Point Numbers for additional information.
6501
6502 Allowed in guard tests.
6503
6504 self() -> pid()
6505
6506 Returns the process identifier of the calling process, for exam‐
6507 ple:
6508
6509 > self().
6510 <0.26.0>
6511
6512 Allowed in guard tests.
6513
6514 erlang:send(Dest, Msg) -> Msg
6515
6516 Types:
6517
6518 Dest = dst()
6519 Msg = term()
6520 dst() =
6521 pid() |
6522 reference() |
6523 port() |
6524 (RegName :: atom()) |
6525 {RegName :: atom(), Node :: node()}
6526
6527 Sends a message and returns Msg. This is the same as using the
6528 send operator: Dest ! Msg.
6529
6530 Dest can be a remote or local process identifier, an alias, a
6531 (local) port, a locally registered name, or a tuple {RegName,
6532 Node} for a registered name at another node.
6533
6534 The function fails with a badarg run-time error if Dest is an
6535 atom name, but this name is not registered. This is the only
6536 case when send fails for an unreachable destination Dest (of
6537 correct type).
6538
6539 erlang:send(Dest, Msg, Options) -> Res
6540
6541 Types:
6542
6543 Dest = dst()
6544 Msg = term()
6545 Options = [nosuspend | noconnect]
6546 Res = ok | nosuspend | noconnect
6547 dst() =
6548 pid() |
6549 reference() |
6550 port() |
6551 (RegName :: atom()) |
6552 {RegName :: atom(), Node :: node()}
6553
6554 Either sends a message and returns ok, or does not send the mes‐
6555 sage but returns something else (see below). Otherwise the same
6556 as erlang:send/2. For more detailed explanation and warnings,
6557 see erlang:send_nosuspend/2,3.
6558
6559 Options:
6560
6561 nosuspend:
6562 If the sender would have to be suspended to do the send, no‐
6563 suspend is returned instead.
6564
6565 noconnect:
6566 If the destination node would have to be auto-connected to
6567 do the send, noconnect is returned instead.
6568
6569 Warning:
6570 As with erlang:send_nosuspend/2,3: use with extreme care.
6571
6572
6573 erlang:send_after(Time, Dest, Msg) -> TimerRef
6574
6575 Types:
6576
6577 Time = integer() >= 0
6578 Dest = pid() | atom()
6579 Msg = term()
6580 TimerRef = reference()
6581
6582 Starts a timer. The same as calling erlang:send_after(Time,
6583 Dest, Msg, []).
6584
6585 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
6586
6587 Types:
6588
6589 Time = integer()
6590 Dest = pid() | atom()
6591 Msg = term()
6592 Options = [Option]
6593 Abs = boolean()
6594 Option = {abs, Abs}
6595 TimerRef = reference()
6596
6597 Starts a timer. When the timer expires, the message Msg is sent
6598 to the process identified by Dest. Apart from the format of the
6599 time-out message, this function works exactly as er‐
6600 lang:start_timer/4.
6601
6602 erlang:send_nosuspend(Dest, Msg) -> boolean()
6603
6604 Types:
6605
6606 Dest = dst()
6607 Msg = term()
6608 dst() =
6609 pid() |
6610 reference() |
6611 port() |
6612 (RegName :: atom()) |
6613 {RegName :: atom(), Node :: node()}
6614
6615 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
6616 true if the message was sent and false if the message was not
6617 sent because the sender would have had to be suspended.
6618
6619 This function is intended for send operations to an unreliable
6620 remote node without ever blocking the sending (Erlang) process.
6621 If the connection to the remote node (usually not a real Erlang
6622 node, but a node written in C or Java) is overloaded, this func‐
6623 tion does not send the message and returns false.
6624
6625 The same occurs if Dest refers to a local port that is busy. For
6626 all other destinations (allowed for the ordinary send operator
6627 '!'), this function sends the message and returns true.
6628
6629 This function is only to be used in rare circumstances where a
6630 process communicates with Erlang nodes that can disappear with‐
6631 out any trace, causing the TCP buffers and the drivers queue to
6632 be over-full before the node is shut down (because of tick time-
6633 outs) by net_kernel. The normal reaction to take when this oc‐
6634 curs is some kind of premature shutdown of the other node.
6635
6636 Notice that ignoring the return value from this function would
6637 result in an unreliable message passing, which is contradictory
6638 to the Erlang programming model. The message is not sent if this
6639 function returns false.
6640
6641 In many systems, transient states of overloaded queues are nor‐
6642 mal. Although this function returns false does not mean that the
6643 other node is guaranteed to be non-responsive, it could be a
6644 temporary overload. Also, a return value of true does only mean
6645 that the message can be sent on the (TCP) channel without block‐
6646 ing; the message is not guaranteed to arrive at the remote node.
6647 For a disconnected non-responsive node, the return value is true
6648 (mimics the behavior of operator !). The expected behavior and
6649 the actions to take when the function returns false are applica‐
6650 tion- and hardware-specific.
6651
6652 Warning:
6653 Use with extreme care.
6654
6655
6656 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
6657
6658 Types:
6659
6660 Dest = dst()
6661 Msg = term()
6662 Options = [noconnect]
6663 dst() =
6664 pid() |
6665 reference() |
6666 port() |
6667 (RegName :: atom()) |
6668 {RegName :: atom(), Node :: node()}
6669
6670 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
6671 with a Boolean return value.
6672
6673 This function behaves like erlang:send_nosuspend/2, but takes a
6674 third parameter, a list of options. The only option is nocon‐
6675 nect, which makes the function return false if the remote node
6676 is not currently reachable by the local node. The normal behav‐
6677 ior is to try to connect to the node, which can stall the
6678 process during a short period. The use of option noconnect makes
6679 it possible to be sure not to get the slightest delay when send‐
6680 ing to a remote process. This is especially useful when communi‐
6681 cating with nodes that expect to always be the connecting part
6682 (that is, nodes written in C or Java).
6683
6684 Whenever the function returns false (either when a suspend would
6685 occur or when noconnect was specified and the node was not al‐
6686 ready connected), the message is guaranteed not to have been
6687 sent.
6688
6689 Warning:
6690 Use with extreme care.
6691
6692
6693 erlang:set_cookie(Cookie) -> true
6694
6695 Types:
6696
6697 Cookie = atom()
6698
6699 Sets the magic cookie of the local node to the atom Cookie,
6700 which is also the cookie for all nodes that have no explicit
6701 cookie set with set_cookie/2 Cookie (see section Distributed
6702 Erlang in the Erlang Reference Manual in System Documentation).
6703
6704 Failure: function_clause if the local node is not alive.
6705
6706 erlang:set_cookie(Node, Cookie) -> true
6707
6708 Types:
6709
6710 Node = node()
6711 Cookie = atom()
6712
6713 Sets the magic cookie for Node to the atom Cookie. If Node is
6714 the local node, the function sets the cookie of all other nodes
6715 (that have no explicit cookie set with this function) to Cookie
6716 (see section Distributed Erlang in the Erlang Reference Manual
6717 in System Documentation).
6718
6719 Failure: function_clause if the local node is not alive.
6720
6721 setelement(Index, Tuple1, Value) -> Tuple2
6722
6723 Types:
6724
6725 Index = integer() >= 1
6726 1..tuple_size(Tuple1
6727 Tuple1 = Tuple2 = tuple()
6728 Value = term()
6729
6730 Returns a tuple that is a copy of argument Tuple1 with the ele‐
6731 ment specified by integer argument Index (the first element is
6732 the element with index 1) replaced by argument Value, for exam‐
6733 ple:
6734
6735 > setelement(2, {10, green, bottles}, red).
6736 {10,red,bottles}
6737
6738 size(Item) -> integer() >= 0
6739
6740 Types:
6741
6742 Item = tuple() | binary()
6743
6744 Returns the number of elements in a tuple or the number of bytes
6745 in a binary or bitstring, for example:
6746
6747 > size({morni, mulle, bwange}).
6748 3
6749 > size(<<11, 22, 33>>).
6750 3
6751
6752 For bitstrings, the number of whole bytes is returned. That is,
6753 if the number of bits in the bitstring is not divisible by 8,
6754 the resulting number of bytes is rounded down.
6755
6756 Allowed in guard tests.
6757
6758 See also tuple_size/1, byte_size/1, and bit_size/1.
6759
6760 spawn(Fun) -> pid()
6761
6762 Types:
6763
6764 Fun = function()
6765
6766 Returns the process identifier of a new process started by the
6767 application of Fun to the empty list []. Otherwise works like
6768 spawn/3.
6769
6770 spawn(Node, Fun) -> pid()
6771
6772 Types:
6773
6774 Node = node()
6775 Fun = function()
6776
6777 Returns the process identifier of a new process started by the
6778 application of Fun to the empty list [] on Node. If Node does
6779 not exist, a useless pid is returned. Otherwise works like
6780 spawn/3.
6781
6782 spawn(Module, Function, Args) -> pid()
6783
6784 Types:
6785
6786 Module = module()
6787 Function = atom()
6788 Args = [term()]
6789
6790 Returns the process identifier of a new process started by the
6791 application of Module:Function to Args.
6792
6793 error_handler:undefined_function(Module, Function, Args) is
6794 evaluated by the new process if Module:Function/Arity does not
6795 exist (where Arity is the length of Args). The error handler can
6796 be redefined (see process_flag/2). If error_handler is unde‐
6797 fined, or the user has redefined the default error_handler and
6798 its replacement is undefined, a failure with reason undef oc‐
6799 curs.
6800
6801 Example:
6802
6803 > spawn(speed, regulator, [high_speed, thin_cut]).
6804 <0.13.1>
6805
6806 spawn(Node, Module, Function, Args) -> pid()
6807
6808 Types:
6809
6810 Node = node()
6811 Module = module()
6812 Function = atom()
6813 Args = [term()]
6814
6815 Returns the process identifier (pid) of a new process started by
6816 the application of Module:Function to Args on Node. If Node does
6817 not exist, a useless pid is returned. Otherwise works like
6818 spawn/3.
6819
6820 spawn_link(Fun) -> pid()
6821
6822 Types:
6823
6824 Fun = function()
6825
6826 Returns the process identifier of a new process started by the
6827 application of Fun to the empty list []. A link is created be‐
6828 tween the calling process and the new process, atomically. Oth‐
6829 erwise works like spawn/3.
6830
6831 spawn_link(Node, Fun) -> pid()
6832
6833 Types:
6834
6835 Node = node()
6836 Fun = function()
6837
6838 Returns the process identifier (pid) of a new process started by
6839 the application of Fun to the empty list [] on Node. A link is
6840 created between the calling process and the new process, atomi‐
6841 cally. If Node does not exist, a useless pid is returned and an
6842 exit signal with reason noconnection is sent to the calling
6843 process. Otherwise works like spawn/3.
6844
6845 spawn_link(Module, Function, Args) -> pid()
6846
6847 Types:
6848
6849 Module = module()
6850 Function = atom()
6851 Args = [term()]
6852
6853 Returns the process identifier of a new process started by the
6854 application of Module:Function to Args. A link is created be‐
6855 tween the calling process and the new process, atomically. Oth‐
6856 erwise works like spawn/3.
6857
6858 spawn_link(Node, Module, Function, Args) -> pid()
6859
6860 Types:
6861
6862 Node = node()
6863 Module = module()
6864 Function = atom()
6865 Args = [term()]
6866
6867 Returns the process identifier (pid) of a new process started by
6868 the application of Module:Function to Args on Node. A link is
6869 created between the calling process and the new process, atomi‐
6870 cally. If Node does not exist, a useless pid is returned and an
6871 exit signal with reason noconnection is sent to the calling
6872 process. Otherwise works like spawn/3.
6873
6874 spawn_monitor(Fun) -> {pid(), reference()}
6875
6876 Types:
6877
6878 Fun = function()
6879
6880 Returns the process identifier of a new process, started by the
6881 application of Fun to the empty list [], and a reference for a
6882 monitor created to the new process. Otherwise works like
6883 spawn/3.
6884
6885 spawn_monitor(Node, Fun) -> {pid(), reference()}
6886
6887 Types:
6888
6889 Node = node()
6890 Fun = function()
6891
6892 Returns the process identifier of a new process, started by the
6893 application of Fun to the empty list [] on the node Node, and a
6894 reference for a monitor created to the new process. Otherwise
6895 works like spawn/3.
6896
6897 If the node identified by Node does not support distributed
6898 spawn_monitor(), the call will fail with a notsup exception.
6899
6900 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6901
6902 Types:
6903
6904 Module = module()
6905 Function = atom()
6906 Args = [term()]
6907
6908 A new process is started by the application of Module:Function
6909 to Args. The process is monitored at the same time. Returns the
6910 process identifier and a reference for the monitor. Otherwise
6911 works like spawn/3.
6912
6913 spawn_monitor(Node, Module, Function, Args) ->
6914 {pid(), reference()}
6915
6916 Types:
6917
6918 Node = node()
6919 Module = module()
6920 Function = atom()
6921 Args = [term()]
6922
6923 A new process is started by the application of Module:Function
6924 to Args on the node Node. The process is monitored at the same
6925 time. Returns the process identifier and a reference for the
6926 monitor. Otherwise works like spawn/3.
6927
6928 If the node identified by Node does not support distributed
6929 spawn_monitor(), the call will fail with a notsup exception.
6930
6931 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6932
6933 Types:
6934
6935 Fun = function()
6936 Options = [spawn_opt_option()]
6937 priority_level() = low | normal | high | max
6938 max_heap_size() =
6939 integer() >= 0 |
6940 #{size => integer() >= 0,
6941 kill => boolean(),
6942 error_logger => boolean()}
6943 message_queue_data() = off_heap | on_heap
6944 spawn_opt_option() =
6945 link | monitor |
6946 {monitor, MonitorOpts :: [monitor_option()]} |
6947 {priority, Level :: priority_level()} |
6948 {fullsweep_after, Number :: integer() >= 0} |
6949 {min_heap_size, Size :: integer() >= 0} |
6950 {min_bin_vheap_size, VSize :: integer() >= 0} |
6951 {max_heap_size, Size :: max_heap_size()} |
6952 {message_queue_data, MQD :: message_queue_data()}
6953
6954 Returns the process identifier (pid) of a new process started by
6955 the application of Fun to the empty list []. Otherwise works
6956 like spawn_opt/4.
6957
6958 If option monitor is specified, the newly created process is
6959 monitored, and both the pid and reference for the monitor are
6960 returned.
6961
6962 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6963
6964 Types:
6965
6966 Node = node()
6967 Fun = function()
6968 Options =
6969 [monitor | {monitor, [monitor_option()]} | link | Oth‐
6970 erOption]
6971 OtherOption = term()
6972
6973 Returns the process identifier (pid) of a new process started by
6974 the application of Fun to the empty list [] on Node. If Node
6975 does not exist, a useless pid is returned. Otherwise works like
6976 spawn_opt/4.
6977
6978 Valid options depends on what options are supported by the node
6979 identified by Node. A description of valid Options for the local
6980 node of current OTP version can be found in the documentation of
6981 spawn_opt/4.
6982
6983 spawn_opt(Module, Function, Args, Options) ->
6984 Pid | {Pid, MonitorRef}
6985
6986 Types:
6987
6988 Module = module()
6989 Function = atom()
6990 Args = [term()]
6991 Options = [spawn_opt_option()]
6992 Pid = pid()
6993 MonitorRef = reference()
6994 priority_level() = low | normal | high | max
6995 max_heap_size() =
6996 integer() >= 0 |
6997 #{size => integer() >= 0,
6998 kill => boolean(),
6999 error_logger => boolean()}
7000 message_queue_data() = off_heap | on_heap
7001 spawn_opt_option() =
7002 link | monitor |
7003 {monitor, MonitorOpts :: [monitor_option()]} |
7004 {priority, Level :: priority_level()} |
7005 {fullsweep_after, Number :: integer() >= 0} |
7006 {min_heap_size, Size :: integer() >= 0} |
7007 {min_bin_vheap_size, VSize :: integer() >= 0} |
7008 {max_heap_size, Size :: max_heap_size()} |
7009 {message_queue_data, MQD :: message_queue_data()}
7010
7011 Works as spawn/3, except that an extra option list is specified
7012 when creating the process.
7013
7014 If option monitor is specified, the newly created process is
7015 monitored, and both the pid and reference for the monitor are
7016 returned.
7017
7018 Options:
7019
7020 link:
7021 Sets a link to the parent process (like spawn_link/3 does).
7022
7023 monitor:
7024 Monitors the new process (like monitor(process, Pid) does).
7025 A {Pid, MonitorRef} tuple will be returned instead of just a
7026 Pid.
7027
7028 {monitor, MonitorOpts}:
7029 Monitors the new process with options (like monitor(process,
7030 Pid, MonitorOpts) does). A {Pid, MonitorRef} tuple will be
7031 returned instead of just a Pid.
7032
7033 {priority, Level}:
7034 Sets the priority of the new process. Equivalent to execut‐
7035 ing process_flag(priority, Level) in the start function of
7036 the new process, except that the priority is set before the
7037 process is selected for execution for the first time. For
7038 more information on priorities, see process_flag(priority,
7039 Level).
7040
7041 {fullsweep_after, Number}:
7042 Useful only for performance tuning. Do not use this option
7043 unless you know that there is problem with execution times
7044 or memory consumption, and ensure that the option improves
7045 matters.
7046
7047 The Erlang runtime system uses a generational garbage col‐
7048 lection scheme, using an "old heap" for data that has sur‐
7049 vived at least one garbage collection. When there is no more
7050 room on the old heap, a fullsweep garbage collection is
7051 done.
7052
7053 Option fullsweep_after makes it possible to specify the max‐
7054 imum number of generational collections before forcing a
7055 fullsweep, even if there is room on the old heap. Setting
7056 the number to zero disables the general collection algo‐
7057 rithm, that is, all live data is copied at every garbage
7058 collection.
7059
7060 A few cases when it can be useful to change fullsweep_after:
7061
7062 * If binaries that are no longer used are to be thrown away
7063 as soon as possible. (Set Number to zero.)
7064
7065 * A process that mostly have short-lived data is fullsweeped
7066 seldom or never, that is, the old heap contains mostly
7067 garbage. To ensure a fullsweep occasionally, set Number to
7068 a suitable value, such as 10 or 20.
7069
7070 * In embedded systems with a limited amount of RAM and no
7071 virtual memory, you might want to preserve memory by set‐
7072 ting Number to zero. (The value can be set globally, see
7073 erlang:system_flag/2.)
7074
7075 {min_heap_size, Size}:
7076 Useful only for performance tuning. Do not use this option
7077 unless you know that there is problem with execution times
7078 or memory consumption, and ensure that the option improves
7079 matters.
7080
7081 Gives a minimum heap size, in words. Setting this value
7082 higher than the system default can speed up some processes
7083 because less garbage collection is done. However, setting a
7084 too high value can waste memory and slow down the system be‐
7085 cause of worse data locality. Therefore, use this option
7086 only for fine-tuning an application and to measure the exe‐
7087 cution time with various Size values.
7088
7089 {min_bin_vheap_size, VSize}:
7090 Useful only for performance tuning. Do not use this option
7091 unless you know that there is problem with execution times
7092 or memory consumption, and ensure that the option improves
7093 matters.
7094
7095 Gives a minimum binary virtual heap size, in words. Setting
7096 this value higher than the system default can speed up some
7097 processes because less garbage collection is done. However,
7098 setting a too high value can waste memory. Therefore, use
7099 this option only for fine-tuning an application and to mea‐
7100 sure the execution time with various VSize values.
7101
7102 {max_heap_size, Size}:
7103 Sets the max_heap_size process flag. The default
7104 max_heap_size is determined by command-line argument +hmax
7105 in erl(1). For more information, see the documentation of
7106 process_flag(max_heap_size, Size).
7107
7108 {message_queue_data, MQD}:
7109 Sets the value of the message_queue_data process flag. MQD
7110 can be either off_heap or on_heap. The default value of the
7111 message_queue_data process flag is determined by the com‐
7112 mand-line argument +hmqd in erl(1). For more information,
7113 see the documentation of process_flag(message_queue_data,
7114 MQD).
7115
7116 spawn_opt(Node, Module, Function, Args, Options) ->
7117 pid() | {pid(), reference()}
7118
7119 Types:
7120
7121 Node = node()
7122 Module = module()
7123 Function = atom()
7124 Args = [term()]
7125 Options =
7126 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7127 erOption]
7128 OtherOption = term()
7129
7130 Returns the process identifier (pid) of a new process started by
7131 the application of Module:Function to Args on Node. If Node does
7132 not exist, a useless pid is returned. Otherwise works like
7133 spawn_opt/4.
7134
7135 Valid options depends on what options are supported by the node
7136 identified by Node. A description of valid Options for the local
7137 node of current OTP version can be found in the documentation of
7138 spawn_opt/4.
7139
7140 spawn_request(Fun) -> ReqId
7141
7142 Types:
7143
7144 Fun = function()
7145 ReqId = reference()
7146
7147 The same as the call spawn_request(node(),Fun,[]). That is, a
7148 spawn request on the local node with no options.
7149
7150 spawn_request(Fun, Options) -> ReqId
7151
7152 Types:
7153
7154 Fun = function()
7155 Option =
7156 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7157 tion()
7158 ReplyTag = term()
7159 Reply = yes | no | error_only | success_only
7160 Options = [Option]
7161 ReqId = reference()
7162
7163 The same as the call spawn_request(node(),Fun,Options). That is,
7164 a spawn request on the local node.
7165
7166 spawn_request(Node, Fun) -> ReqId
7167
7168 Types:
7169
7170 Node = node()
7171 Fun = function()
7172 ReqId = reference()
7173
7174 The same as the call spawn_request(Node,Fun,[]). That is, a
7175 spawn request with no options.
7176
7177 spawn_request(Node, Fun, Options) -> ReqId
7178
7179 Types:
7180
7181 Node = node()
7182 Fun = function()
7183 Options = [Option]
7184 Option =
7185 monitor |
7186 {monitor, [monitor_option()]} |
7187 link |
7188 {reply_tag, ReplyTag} |
7189 {reply, Reply} |
7190 OtherOption
7191 ReplyTag = term()
7192 Reply = yes | no | error_only | success_only
7193 OtherOption = term()
7194 ReqId = reference()
7195
7196 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
7197 That is, a spawn request using the fun Fun of arity zero as en‐
7198 try point.
7199
7200 This function will fail with a badarg exception if:
7201
7202 * Node is not an atom.
7203
7204 * Fun is not a fun of arity zero.
7205
7206 * Options is not a proper list of terms.
7207
7208 spawn_request(Module, Function, Args) -> ReqId
7209
7210 Types:
7211
7212 Module = module()
7213 Function = atom()
7214 Args = [term()]
7215 ReqId = reference()
7216
7217 The same as the call spawn_request(node(),Module,Func‐
7218 tion,Args,[]). That is, a spawn request on the local node with
7219 no options.
7220
7221 spawn_request(Node, Module, Function, Args) -> ReqId
7222
7223 Types:
7224
7225 Node = node()
7226 Module = module()
7227 Function = atom()
7228 Args = [term()]
7229 ReqId = reference()
7230
7231 The same as the call spawn_request(Node,Module,Func‐
7232 tion,Args,[]). That is, a spawn request with no options.
7233
7234 spawn_request(Module, Function, Args, Options) -> ReqId
7235
7236 Types:
7237
7238 Module = module()
7239 Function = atom()
7240 Args = [term()]
7241 Option =
7242 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7243 tion()
7244 ReplyTag = term()
7245 Reply = yes | no | error_only | success_only
7246 Options = [Option]
7247 ReqId = reference()
7248
7249 The same as the call spawn_request(node(),Module,Func‐
7250 tion,Args,Options). That is, a spawn request on the local node.
7251
7252 spawn_request(Node, Module, Function, Args, Options) -> ReqId
7253
7254 Types:
7255
7256 Node = node()
7257 Module = module()
7258 Function = atom()
7259 Args = [term()]
7260 Options = [Option]
7261 Option =
7262 monitor |
7263 {monitor, [monitor_option()]} |
7264 link |
7265 {reply_tag, ReplyTag} |
7266 {reply, Reply} |
7267 OtherOption
7268 ReplyTag = term()
7269 Reply = yes | no | error_only | success_only
7270 OtherOption = term()
7271 ReqId = reference()
7272
7273 Asynchronously send a spawn request. Returns a request identi‐
7274 fier ReqId.
7275
7276 If the spawn operation succeeds, a new process is created on the
7277 node identified by Node. When a spawn operation succeeds, the
7278 caller will by default be sent a message on the form {ReplyTag,
7279 ReqId, ok, Pid} where Pid is the process identifier of the newly
7280 created process. Such a message is referred to as a success mes‐
7281 sage below in the text. ReplyTag is by default the atom
7282 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
7283 The new process is started by the application of Module:Function
7284 to Args.
7285
7286 The spawn operation fails either if creation of a new process
7287 failed or if the spawn operation was interrupted by a connection
7288 failure. When a spawn operation fails, the caller will by de‐
7289 fault be sent a message on the form {ReplyTag, ReqId, error,
7290 Reason} where Reason is the error reason. Such a message is re‐
7291 ferred to as an error message below in the text. Currently the
7292 following spawn error Reasons are defined, but other reasons can
7293 appear at any time without prior notice:
7294
7295 badopt:
7296 An invalid Option was passed as argument. Note that differ‐
7297 ent runtime systems may support different options.
7298
7299 notsup:
7300 The node identified by Node does not support spawn opera‐
7301 tions issued by spawn_request().
7302
7303 noconnection:
7304 Failure to set up a connection to the node identified by
7305 Node or the connection to that node was lost during the
7306 spawn operation. In the case the connection was lost, a
7307 process may or may not have been created.
7308
7309 system_limit:
7310 Could not create a new process due to that some system limit
7311 was reached. Typically the process table was full.
7312
7313 Valid Options:
7314
7315 monitor:
7316 In the absence of spawn operation failures, atomically sets
7317 up a monitor to the newly created process. That is, as if
7318 the calling process had called monitor(process, Pid) where
7319 Pid is the process identifier of the newly created process.
7320 The ReqId returned by spawn_request() is also used as moni‐
7321 tor reference as if it was returned from monitor(process,
7322 Pid).
7323
7324 The monitor will not be activated for the calling process
7325 until the spawn operation has succeeded. The monitor can not
7326 be demonitored before the operation has succeeded. A 'DOWN'
7327 message for the corresponding monitor is guaranteed not to
7328 be delivered before a success message that corresponds to
7329 the spawn operation. If the spawn operation fails, no 'DOWN'
7330 message will be delivered.
7331
7332 If the connection between the nodes involved in the spawn
7333 operation is lost during the spawn operation, the spawn op‐
7334 eration will fail with an error reason of noconnection. A
7335 new process may or may not have been created.
7336
7337 {monitor, MonitorOpts}:
7338 In the absence of spawn operation failures, atomically sets
7339 up a monitor to the newly created process. That is, as if
7340 the calling process had called monitor(process, Pid, Moni‐
7341 torOpts) where Pid is the process identifier of the newly
7342 created process. See the monitor option above for more in‐
7343 formation.
7344
7345 Note that the monitor will not be activated for the calling
7346 process until the spawn operation has succeeded. For exam‐
7347 ple, in the case that an alias is created using the monitor
7348 option, the alias will not be active until the monitor is
7349 activated.
7350
7351 link:
7352 In absence of spawn operation failures, atomically sets up a
7353 link between the calling process and the newly created
7354 process. That is, as if the calling process had called
7355 link(Pid) where Pid is the process identifier of the newly
7356 created process.
7357
7358 The link will not be activated for the calling process until
7359 the spawn operation has succeeded. The link can not be re‐
7360 moved before the operation has succeeded. An exit signal due
7361 to the link is guaranteed not to be delivered before a suc‐
7362 cess message that corresponds to the spawn operation. If
7363 the spawn operation fails, no exit signal due to the link
7364 will be delivered to the caller of spawn_request().
7365
7366 If the connection between the nodes involved in the spawn
7367 operation is lost during the spawn operation, the spawn op‐
7368 eration will fail with an error reason of noconnection. A
7369 new process may or may not have been created. If it has been
7370 created, it will be delivered an exit signal with an exit
7371 reason of noconnection.
7372
7373 {reply, Reply}:
7374 Valid Reply values:
7375
7376 yes:
7377 A spawn reply message will be sent to the caller regard‐
7378 less of whether the operation succeeds or not. If the call
7379 to spawn_request() returns without raising an exception
7380 and the reply option is set to yes, the caller is guaran‐
7381 teed to be delivered either a success message or an error
7382 message . The reply option is by default set to yes.
7383
7384 no:
7385 No spawn reply message will be sent to the caller when the
7386 spawn operation completes. This regardless of whether the
7387 operation succeeds or not.
7388
7389 error_only:
7390 No spawn reply message will be sent to the caller if the
7391 spawn operation succeeds, but an error message will be
7392 sent to the caller if the operation fails.
7393
7394 success_only:
7395 No spawn reply message will be sent to the caller if the
7396 spawn operation fails, but a success message will be sent
7397 to the caller if the operation succeeds.
7398
7399 {reply_tag, ReplyTag}:
7400 Sets the reply tag to ReplyTag in the reply message. That
7401 is, in the success or error message that is sent to the
7402 caller due to the spawn operation. The default reply tag is
7403 the atom spawn_reply.
7404
7405 OtherOption:
7406 Other valid options depends on what options are supported by
7407 the node identified by Node. A description of other valid
7408 Options for the local node of current OTP version can be
7409 found in the documentation of spawn_opt/4.
7410
7411 This function will fail with a badarg exception if:
7412
7413 * Node is not an atom.
7414
7415 * Module is not an atom.
7416
7417 * Function is not an atom.
7418
7419 * Args is not a proper list of terms.
7420
7421 * Options is not a proper list of terms.
7422
7423 Note that not all individual Options are checked when the spawn
7424 request is sent. Some Options can only be checked on reception
7425 of the request. Therefore an invalid option does not cause a
7426 badarg exception, but will cause the spawn operation to fail
7427 with an error reason of badopt.
7428
7429 A spawn request can be abandoned by calling spawn_request_aban‐
7430 don/1.
7431
7432 spawn_request_abandon(ReqId :: reference()) -> boolean()
7433
7434 Abandon a previously issued spawn request. ReqId corresponds to
7435 a request identifier previously returned by spawn_request() in a
7436 call from current process. That is, only the process that has
7437 made the request can abandon the request.
7438
7439 A spawn request can only be successfully abandoned until the
7440 spawn request has completed. When a spawn request has been suc‐
7441 cessfully abandoned, the caller will not be effected by future
7442 direct effects of the spawn request itself. For example, it will
7443 not receive a spawn reply message. The request is however not
7444 withdrawn, so a new process may or may not be created due to the
7445 request. If a new process is created after the spawn request was
7446 abandoned, no monitors nor links will be set up to the caller of
7447 spawn_request_abandon/1 due to the spawn request. If the spawn
7448 request included the link option, the process created due to
7449 this request will be sent an exit signal from its parent with
7450 the exit reason abandoned when it is detected that the spawn op‐
7451 eration has succeeded.
7452
7453 Note:
7454 A process created due to a spawn request that has been abandoned
7455 may communicate with its parent as any other process. It is only
7456 the direct effects on the parent of the actual spawn request,
7457 that will be canceled by abandoning a spawn request.
7458
7459
7460 Return values:
7461
7462 true:
7463 The spawn request was successfully abandoned.
7464
7465 false:
7466 No spawn request was abandoned. The ReqId request identifier
7467 did not correspond to an outstanding spawn request issued by
7468 the calling process. The reason for this is either:
7469
7470 * ReqId corresponds to a spawn request previoulsy made by
7471 the calling process. The spawn operation has completed and
7472 a spawn reply has already been delivered to the calling
7473 process unless the spawn reply was disabled in the re‐
7474 quest.
7475
7476 * ReqId does not correspond to a spawn request that has been
7477 made by the calling process.
7478
7479 This function fail with a badarg exception if ReqId is not a
7480 reference.
7481
7482 split_binary(Bin, Pos) -> {binary(), binary()}
7483
7484 Types:
7485
7486 Bin = binary()
7487 Pos = integer() >= 0
7488 0..byte_size(Bin)
7489
7490 Returns a tuple containing the binaries that are the result of
7491 splitting Bin into two parts at position Pos. This is not a de‐
7492 structive operation. After the operation, there are three bina‐
7493 ries altogether. Example:
7494
7495 > B = list_to_binary("0123456789").
7496 <<"0123456789">>
7497 > byte_size(B).
7498 10
7499 > {B1, B2} = split_binary(B,3).
7500 {<<"012">>,<<"3456789">>}
7501 > byte_size(B1).
7502 3
7503 > byte_size(B2).
7504 7
7505
7506 erlang:start_timer(Time, Dest, Msg) -> TimerRef
7507
7508 Types:
7509
7510 Time = integer() >= 0
7511 Dest = pid() | atom()
7512 Msg = term()
7513 TimerRef = reference()
7514
7515 Starts a timer. The same as calling erlang:start_timer(Time,
7516 Dest, Msg, []).
7517
7518 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
7519
7520 Types:
7521
7522 Time = integer()
7523 Dest = pid() | atom()
7524 Msg = term()
7525 Options = [Option]
7526 Abs = boolean()
7527 Option = {abs, Abs}
7528 TimerRef = reference()
7529
7530 Starts a timer. When the timer expires, the message {timeout,
7531 TimerRef, Msg} is sent to the process identified by Dest.
7532
7533 Options:
7534
7535 {abs, false}:
7536 This is the default. It means the Time value is interpreted
7537 as a time in milliseconds relative current Erlang monotonic
7538 time.
7539
7540 {abs, true}:
7541 Absolute Time value. The Time value is interpreted as an ab‐
7542 solute Erlang monotonic time in milliseconds.
7543
7544 More Options can be added in the future.
7545
7546 The absolute point in time, the timer is set to expire on, must
7547 be in the interval [ erlang:convert_time_unit(erlang:sys‐
7548 tem_info(start_time), native, millisecond), erlang:con‐
7549 vert_time_unit(erlang:system_info(end_time), native, millisec‐
7550 ond) ]. If a relative time is specified, the Time value is not
7551 allowed to be negative.
7552
7553 If Dest is a pid(), it must be a pid() of a process created on
7554 the current runtime system instance. This process has either
7555 terminated or not. If Dest is an atom(), it is interpreted as
7556 the name of a locally registered process. The process referred
7557 to by the name is looked up at the time of timer expiration. No
7558 error is returned if the name does not refer to a process.
7559
7560 If Dest is a pid(), the timer is automatically canceled if the
7561 process referred to by the pid() is not alive, or if the process
7562 exits. This feature was introduced in ERTS 5.4.11. Notice that
7563 timers are not automatically canceled when Dest is an atom().
7564
7565 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
7566 lang:read_timer/2.
7567
7568 Failure: badarg if the arguments do not satisfy the requirements
7569 specified here.
7570
7571 statistics(Item :: active_tasks) -> [ActiveTasks]
7572
7573 Types:
7574
7575 ActiveTasks = integer() >= 0
7576
7577 Returns the same as statistics(active_tasks_all) with the excep‐
7578 tion that no information about the dirty IO run queue and its
7579 associated schedulers is part of the result. That is, only tasks
7580 that are expected to be CPU bound are part of the result.
7581
7582 statistics(Item :: active_tasks_all) -> [ActiveTasks]
7583
7584 Types:
7585
7586 ActiveTasks = integer() >= 0
7587
7588 Returns a list where each element represents the amount of ac‐
7589 tive processes and ports on each run queue and its associated
7590 schedulers. That is, the number of processes and ports that are
7591 ready to run, or are currently running. Values for normal run
7592 queues and their associated schedulers are located first in the
7593 resulting list. The first element corresponds to scheduler num‐
7594 ber 1 and so on. If support for dirty schedulers exist, an ele‐
7595 ment with the value for the dirty CPU run queue and its associ‐
7596 ated dirty CPU schedulers follow and then as last element the
7597 value for the the dirty IO run queue and its associated dirty IO
7598 schedulers follow. The information is not gathered atomically.
7599 That is, the result is not necessarily a consistent snapshot of
7600 the state, but instead quite efficiently gathered.
7601
7602 Note:
7603 Each normal scheduler has one run queue that it manages. If
7604 dirty schedulers schedulers are supported, all dirty CPU sched‐
7605 ulers share one run queue, and all dirty IO schedulers share one
7606 run queue. That is, we have multiple normal run queues, one
7607 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7608 grate between the different types of run queues. Only work in
7609 normal run queues can migrate to other normal run queues. This
7610 has to be taken into account when evaluating the result.
7611
7612
7613 See also statistics(total_active_tasks), statis‐
7614 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
7615 tistics(total_run_queue_lengths), and statistics(to‐
7616 tal_run_queue_lengths_all).
7617
7618 statistics(Item :: context_switches) -> {ContextSwitches, 0}
7619
7620 Types:
7621
7622 ContextSwitches = integer() >= 0
7623
7624 Returns the total number of context switches since the system
7625 started.
7626
7627 statistics(Item :: exact_reductions) ->
7628 {Total_Exact_Reductions,
7629 Exact_Reductions_Since_Last_Call}
7630
7631 Types:
7632
7633 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
7634 integer() >= 0
7635
7636 Returns the number of exact reductions.
7637
7638 Note:
7639 statistics(exact_reductions) is a more expensive operation than
7640 statistics(reductions).
7641
7642
7643 statistics(Item :: garbage_collection) ->
7644 {Number_of_GCs, Words_Reclaimed, 0}
7645
7646 Types:
7647
7648 Number_of_GCs = Words_Reclaimed = integer() >= 0
7649
7650 Returns information about garbage collection, for example:
7651
7652 > statistics(garbage_collection).
7653 {85,23961,0}
7654
7655 This information can be invalid for some implementations.
7656
7657 statistics(Item :: io) -> {{input, Input}, {output, Output}}
7658
7659 Types:
7660
7661 Input = Output = integer() >= 0
7662
7663 Returns Input, which is the total number of bytes received
7664 through ports, and Output, which is the total number of bytes
7665 output to ports.
7666
7667 statistics(Item :: microstate_accounting) ->
7668 [MSAcc_Thread] | undefined
7669
7670 Types:
7671
7672 MSAcc_Thread =
7673 #{type := MSAcc_Thread_Type,
7674 id := MSAcc_Thread_Id,
7675 counters := MSAcc_Counters}
7676 MSAcc_Thread_Type =
7677 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
7678 poll | scheduler
7679 MSAcc_Thread_Id = integer() >= 0
7680 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
7681 MSAcc_Thread_State =
7682 alloc | aux | bif | busy_wait | check_io | emulator | ets
7683 |
7684 gc | gc_fullsweep | nif | other | port | send | sleep |
7685 timers
7686
7687 Microstate accounting can be used to measure how much time the
7688 Erlang runtime system spends doing various tasks. It is designed
7689 to be as lightweight as possible, but some overhead exists when
7690 this is enabled. Microstate accounting is meant to be a profil‐
7691 ing tool to help finding performance bottlenecks. To
7692 start/stop/reset microstate accounting, use system flag mi‐
7693 crostate_accounting.
7694
7695 statistics(microstate_accounting) returns a list of maps repre‐
7696 senting some of the OS threads within ERTS. Each map contains
7697 type and id fields that can be used to identify what thread it
7698 is, and also a counters field that contains data about how much
7699 time has been spent in the various states.
7700
7701 Example:
7702
7703 > erlang:statistics(microstate_accounting).
7704 [#{counters => #{aux => 1899182914,
7705 check_io => 2605863602,
7706 emulator => 45731880463,
7707 gc => 1512206910,
7708 other => 5421338456,
7709 port => 221631,
7710 sleep => 5150294100},
7711 id => 1,
7712 type => scheduler}|...]
7713
7714 The time unit is the same as returned by os:perf_counter/0. So,
7715 to convert it to milliseconds, you can do something like this:
7716
7717 lists:map(
7718 fun(#{ counters := Cnt } = M) ->
7719 MsCnt = maps:map(fun(_K, PerfCount) ->
7720 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
7721 end, Cnt),
7722 M#{ counters := MsCnt }
7723 end, erlang:statistics(microstate_accounting)).
7724
7725 Notice that these values are not guaranteed to be the exact time
7726 spent in each state. This is because of various optimisation
7727 done to keep the overhead as small as possible.
7728
7729 MSAcc_Thread_Types:
7730
7731 scheduler:
7732 The main execution threads that do most of the work. See erl
7733 +S for more details.
7734
7735 dirty_cpu_scheduler:
7736 The threads for long running cpu intensive work. See erl
7737 +SDcpu for more details.
7738
7739 dirty_io_scheduler:
7740 The threads for long running I/O work. See erl +SDio for
7741 more details.
7742
7743 async:
7744 Async threads are used by various linked-in drivers (mainly
7745 the file drivers) do offload non-CPU intensive work. See erl
7746 +A for more details.
7747
7748 aux:
7749 Takes care of any work that is not specifically assigned to
7750 a scheduler.
7751
7752 poll:
7753 Does the IO polling for the emulator. See erl +IOt for more
7754 details.
7755
7756 The following MSAcc_Thread_States are available. All states are
7757 exclusive, meaning that a thread cannot be in two states at
7758 once. So, if you add the numbers of all counters in a thread,
7759 you get the total runtime for that thread.
7760
7761 aux:
7762 Time spent handling auxiliary jobs.
7763
7764 check_io:
7765 Time spent checking for new I/O events.
7766
7767 emulator:
7768 Time spent executing Erlang processes.
7769
7770 gc:
7771 Time spent doing garbage collection. When extra states are
7772 enabled this is the time spent doing non-fullsweep garbage
7773 collections.
7774
7775 other:
7776 Time spent doing unaccounted things.
7777
7778 port:
7779 Time spent executing ports.
7780
7781 sleep:
7782 Time spent sleeping.
7783
7784 More fine-grained MSAcc_Thread_States can be added through con‐
7785 figure (such as ./configure --with-microstate-accounting=extra).
7786 Enabling these states causes performance degradation when mi‐
7787 crostate accounting is turned off and increases the overhead
7788 when it is turned on.
7789
7790 alloc:
7791 Time spent managing memory. Without extra states this time
7792 is spread out over all other states.
7793
7794 bif:
7795 Time spent in BIFs. Without extra states this time is part
7796 of the emulator state.
7797
7798 busy_wait:
7799 Time spent busy waiting. This is also the state where a
7800 scheduler no longer reports that it is active when using
7801 statistics(scheduler_wall_time). So, if you add all other
7802 states but this and sleep, and then divide that by all time
7803 in the thread, you should get something very similar to the
7804 scheduler_wall_time fraction. Without extra states this time
7805 is part of the other state.
7806
7807 ets:
7808 Time spent executing ETS BIFs. Without extra states this
7809 time is part of the emulator state.
7810
7811 gc_full:
7812 Time spent doing fullsweep garbage collection. Without extra
7813 states this time is part of the gc state.
7814
7815 nif:
7816 Time spent in NIFs. Without extra states this time is part
7817 of the emulator state.
7818
7819 send:
7820 Time spent sending messages (processes only). Without extra
7821 states this time is part of the emulator state.
7822
7823 timers:
7824 Time spent managing timers. Without extra states this time
7825 is part of the other state.
7826
7827 The utility module msacc(3) can be used to more easily analyse
7828 these statistics.
7829
7830 Returns undefined if system flag microstate_accounting is turned
7831 off.
7832
7833 The list of thread information is unsorted and can appear in
7834 different order between calls.
7835
7836 Note:
7837 The threads and states are subject to change without any prior
7838 notice.
7839
7840
7841 statistics(Item :: reductions) ->
7842 {Total_Reductions, Reductions_Since_Last_Call}
7843
7844 Types:
7845
7846 Total_Reductions = Reductions_Since_Last_Call = integer() >=
7847 0
7848
7849 Returns information about reductions, for example:
7850
7851 > statistics(reductions).
7852 {2046,11}
7853
7854 Note:
7855 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
7856 reductions performed in current time slices of currently sched‐
7857 uled processes. If an exact value is wanted, use statistics(ex‐
7858 act_reductions).
7859
7860
7861 statistics(Item :: run_queue) -> integer() >= 0
7862
7863 Returns the total length of all normal and dirty CPU run queues.
7864 That is, queued work that is expected to be CPU bound. The in‐
7865 formation is gathered atomically. That is, the result is a con‐
7866 sistent snapshot of the state, but this operation is much more
7867 expensive compared to statistics(total_run_queue_lengths), espe‐
7868 cially when a large amount of schedulers is used.
7869
7870 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
7871
7872 Types:
7873
7874 RunQueueLength = integer() >= 0
7875
7876 Returns the same as statistics(run_queue_lengths_all) with the
7877 exception that no information about the dirty IO run queue is
7878 part of the result. That is, only run queues with work that is
7879 expected to be CPU bound is part of the result.
7880
7881 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
7882
7883 Types:
7884
7885 RunQueueLength = integer() >= 0
7886
7887 Returns a list where each element represents the amount of pro‐
7888 cesses and ports ready to run for each run queue. Values for
7889 normal run queues are located first in the resulting list. The
7890 first element corresponds to the normal run queue of scheduler
7891 number 1 and so on. If support for dirty schedulers exist, val‐
7892 ues for the dirty CPU run queue and the dirty IO run queue fol‐
7893 low (in that order) at the end. The information is not gathered
7894 atomically. That is, the result is not necessarily a consistent
7895 snapshot of the state, but instead quite efficiently gathered.
7896
7897 Note:
7898 Each normal scheduler has one run queue that it manages. If
7899 dirty schedulers schedulers are supported, all dirty CPU sched‐
7900 ulers share one run queue, and all dirty IO schedulers share one
7901 run queue. That is, we have multiple normal run queues, one
7902 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7903 grate between the different types of run queues. Only work in
7904 normal run queues can migrate to other normal run queues. This
7905 has to be taken into account when evaluating the result.
7906
7907
7908 See also statistics(run_queue_lengths), statistics(to‐
7909 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
7910 statistics(active_tasks), statistics(active_tasks_all), and sta‐
7911 tistics(total_active_tasks), statistics(total_active_tasks_all).
7912
7913 statistics(Item :: runtime) ->
7914 {Total_Run_Time, Time_Since_Last_Call}
7915
7916 Types:
7917
7918 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
7919
7920 Returns information about runtime, in milliseconds.
7921
7922 This is the sum of the runtime for all threads in the Erlang
7923 runtime system and can therefore be greater than the wall clock
7924 time.
7925
7926 Warning:
7927 This value might wrap due to limitations in the underlying func‐
7928 tionality provided by the operating system that is used.
7929
7930
7931 Example:
7932
7933 > statistics(runtime).
7934 {1690,1620}
7935
7936 statistics(Item :: scheduler_wall_time) ->
7937 [{SchedulerId, ActiveTime, TotalTime}] | undefined
7938
7939 Types:
7940
7941 SchedulerId = integer() >= 1
7942 ActiveTime = TotalTime = integer() >= 0
7943
7944 Returns information describing how much time normal and dirty
7945 CPU schedulers in the system have been busy. This value is nor‐
7946 mally a better indicator of how much load an Erlang node is un‐
7947 der instead of looking at the CPU utilization privided by tools
7948 such as top or sysstat. This is because scheduler_wall_time also
7949 includes time where the scheduler is waiting for some other rea‐
7950 source (such as an internal mutex) to be available but does not
7951 use the CPU. In order to better understand what a scheduler is
7952 busy doing you can use microstate accounting.
7953
7954 The definition of a busy scheduler is when it is not idle and
7955 not busy waiting for new work, that is:
7956
7957 * Executing process code
7958
7959 * Executing linked-in driver or NIF code
7960
7961 * Executing BIFs, or any other runtime handling
7962
7963 * Garbage collecting
7964
7965 * Handling any other memory management
7966
7967 Notice that a scheduler can also be busy even if the OS has
7968 scheduled out the scheduler thread.
7969
7970 Note:
7971 It is recommended to use the module scheduler instead of this
7972 function directly as it provides an easier way to get the infor‐
7973 mation that you usually want.
7974
7975
7976 If enabled this function returns a list of tuples with {Schedu‐
7977 lerId, ActiveTime, TotalTime}, where SchedulerId is an integer
7978 ID of the scheduler, ActiveTime is the duration the scheduler
7979 has been busy, and TotalTime is the total time duration since
7980 scheduler_wall_time activation for the specific scheduler. The
7981 time unit returned is undefined and can be subject to change be‐
7982 tween releases, OSs, and system restarts. scheduler_wall_time is
7983 only to be used to calculate relative values for scheduler uti‐
7984 lization. The ActiveTime can never exceed TotalTime. The list of
7985 scheduler information is unsorted and can appear in different
7986 order between calls.
7987
7988 The disabled this function returns undefined.
7989
7990 The activation time can differ significantly between schedulers.
7991 Currently dirty schedulers are activated at system start while
7992 normal schedulers are activated some time after the sched‐
7993 uler_wall_time functionality is enabled.
7994
7995 Only information about schedulers that are expected to handle
7996 CPU bound work is included in the return values from this func‐
7997 tion. If you also want information about dirty I/O schedulers,
7998 use statistics(scheduler_wall_time_all) instead.
7999
8000 Normal schedulers will have scheduler identifiers in the range 1
8001 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
8002 schedulers will have scheduler identifiers in the range er‐
8003 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
8004 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
8005
8006 Note:
8007 The different types of schedulers handle specific types of jobs.
8008 Every job is assigned to a specific scheduler type. Jobs can mi‐
8009 grate between different schedulers of the same type, but never
8010 between schedulers of different types. This fact has to be taken
8011 under consideration when evaluating the result returned.
8012
8013
8014 You can use scheduler_wall_time to calculate scheduler utiliza‐
8015 tion. First you take a sample of the values returned by er‐
8016 lang:statistics(scheduler_wall_time).
8017
8018 > erlang:system_flag(scheduler_wall_time, true).
8019 false
8020 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8021 ok
8022
8023 Some time later the user takes another snapshot and calculates
8024 scheduler utilization per scheduler, for example:
8025
8026 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8027 ok
8028 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
8029 [{1,0.9743474730177548},
8030 {2,0.9744843782751444},
8031 {3,0.9995902361669045},
8032 {4,0.9738012596572161},
8033 {5,0.9717956667018103},
8034 {6,0.9739235846420741},
8035 {7,0.973237033077876},
8036 {8,0.9741297293248656}]
8037
8038 Using the same snapshots to calculate a total scheduler utiliza‐
8039 tion:
8040
8041 > {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.
8042 0.9769136803764825
8043
8044 Total scheduler utilization will equal 1.0 when all schedulers
8045 have been active all the time between the two measurements.
8046
8047 Another (probably more) useful value is to calculate total
8048 scheduler utilization weighted against maximum amount of avail‐
8049 able CPU time:
8050
8051 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
8052 0.9769136803764825
8053
8054 This weighted scheduler utilization will reach 1.0 when sched‐
8055 ulers are active the same amount of time as maximum available
8056 CPU time. If more schedulers exist than available logical pro‐
8057 cessors, this value may be greater than 1.0.
8058
8059 As of ERTS version 9.0, the Erlang runtime system will as de‐
8060 fault have more schedulers than logical processors. This due to
8061 the dirty schedulers.
8062
8063 Note:
8064 scheduler_wall_time is by default disabled. To enable it, use
8065 erlang:system_flag(scheduler_wall_time, true).
8066
8067
8068 statistics(Item :: scheduler_wall_time_all) ->
8069 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8070
8071 Types:
8072
8073 SchedulerId = integer() >= 1
8074 ActiveTime = TotalTime = integer() >= 0
8075
8076 The same as statistics(scheduler_wall_time), except that it also
8077 include information about all dirty I/O schedulers.
8078
8079 Dirty IO schedulers will have scheduler identifiers in the range
8080 erlang:system_info(schedulers) + erlang:sys‐
8081 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
8082 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
8083 + erlang:system_info(dirty_io_schedulers).
8084
8085 Note:
8086 Note that work executing on dirty I/O schedulers are expected to
8087 mainly wait for I/O. That is, when you get high scheduler uti‐
8088 lization on dirty I/O schedulers, CPU utilization is not ex‐
8089 pected to be high due to this work.
8090
8091
8092 statistics(Item :: total_active_tasks) -> ActiveTasks
8093
8094 Types:
8095
8096 ActiveTasks = integer() >= 0
8097
8098 The same as calling lists:sum(statistics(active_tasks)), but
8099 more efficient.
8100
8101 statistics(Item :: total_active_tasks_all) -> ActiveTasks
8102
8103 Types:
8104
8105 ActiveTasks = integer() >= 0
8106
8107 The same as calling lists:sum(statistics(active_tasks_all)), but
8108 more efficient.
8109
8110 statistics(Item :: total_run_queue_lengths) ->
8111 TotalRunQueueLengths
8112
8113 Types:
8114
8115 TotalRunQueueLengths = integer() >= 0
8116
8117 The same as calling lists:sum(statistics(run_queue_lengths)),
8118 but more efficient.
8119
8120 statistics(Item :: total_run_queue_lengths_all) ->
8121 TotalRunQueueLengths
8122
8123 Types:
8124
8125 TotalRunQueueLengths = integer() >= 0
8126
8127 The same as calling lists:sum(statis‐
8128 tics(run_queue_lengths_all)), but more efficient.
8129
8130 statistics(Item :: wall_clock) ->
8131 {Total_Wallclock_Time,
8132 Wallclock_Time_Since_Last_Call}
8133
8134 Types:
8135
8136 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
8137 ger() >= 0
8138
8139 Returns information about wall clock. wall_clock can be used in
8140 the same manner as runtime, except that real time is measured as
8141 opposed to runtime or CPU time.
8142
8143 erlang:suspend_process(Suspendee) -> true
8144
8145 Types:
8146
8147 Suspendee = pid()
8148
8149 Suspends the process identified by Suspendee. The same as call‐
8150 ing erlang:suspend_process(Suspendee, []).
8151
8152 Warning:
8153 This BIF is intended for debugging only.
8154
8155
8156 erlang:suspend_process(Suspendee, OptList) -> boolean()
8157
8158 Types:
8159
8160 Suspendee = pid()
8161 OptList = [Opt]
8162 Opt = unless_suspending | asynchronous | {asynchronous,
8163 term()}
8164
8165 Increases the suspend count on the process identified by Sus‐
8166 pendee and puts it in the suspended state if it is not already
8167 in that state. A suspended process is not scheduled for execu‐
8168 tion until the process has been resumed.
8169
8170 A process can be suspended by multiple processes and can be sus‐
8171 pended multiple times by a single process. A suspended process
8172 does not leave the suspended state until its suspend count
8173 reaches zero. The suspend count of Suspendee is decreased when
8174 erlang:resume_process(Suspendee) is called by the same process
8175 that called erlang:suspend_process(Suspendee). All increased
8176 suspend counts on other processes acquired by a process are au‐
8177 tomatically decreased when the process terminates.
8178
8179 Options (Opts):
8180
8181 asynchronous:
8182 A suspend request is sent to the process identified by Sus‐
8183 pendee. Suspendee eventually suspends unless it is resumed
8184 before it could suspend. The caller of erlang:sus‐
8185 pend_process/2 returns immediately, regardless of whether
8186 Suspendee has suspended yet or not. The point in time when
8187 Suspendee suspends cannot be deduced from other events in
8188 the system. It is only guaranteed that Suspendee eventually
8189 suspends (unless it is resumed). If no asynchronous options
8190 has been passed, the caller of erlang:suspend_process/2 is
8191 blocked until Suspendee has suspended.
8192
8193 {asynchronous, ReplyTag}:
8194 A suspend request is sent to the process identified by Sus‐
8195 pendee. When the suspend request has been processed, a reply
8196 message is sent to the caller of this function. The reply is
8197 on the form {ReplyTag, State} where State is either:
8198
8199 exited:
8200 Suspendee has exited.
8201
8202 suspended:
8203 Suspendee is now suspended.
8204
8205 not_suspended:
8206 Suspendee is not suspended. This can only happen when the
8207 process that issued this request, have called re‐
8208 sume_process(Suspendee) before getting the reply.
8209
8210 Appart from the reply message, the {asynchronous, ReplyTag}
8211 option behaves exactly the same as the asynchronous option
8212 without reply tag.
8213
8214 unless_suspending:
8215 The process identified by Suspendee is suspended unless the
8216 calling process already is suspending Suspendee. If un‐
8217 less_suspending is combined with option asynchronous, a sus‐
8218 pend request is sent unless the calling process already is
8219 suspending Suspendee or if a suspend request already has
8220 been sent and is in transit. If the calling process already
8221 is suspending Suspendee, or if combined with option asyn‐
8222 chronous and a send request already is in transit, false is
8223 returned and the suspend count on Suspendee remains un‐
8224 changed.
8225
8226 If the suspend count on the process identified by Suspendee is
8227 increased, true is returned, otherwise false.
8228
8229 Warning:
8230 This BIF is intended for debugging only.
8231
8232
8233 Warning:
8234 You can easily create deadlocks if processes suspends each other
8235 (directly or in circles). In ERTS versions prior to ERTS version
8236 10.0, the runtime system prevented such deadlocks, but this pre‐
8237 vention has now been removed due to performance reasons.
8238
8239
8240 Failures:
8241
8242 badarg:
8243 If Suspendee is not a process identifier.
8244
8245 badarg:
8246 If the process identified by Suspendee is the same process
8247 as the process calling erlang:suspend_process/2.
8248
8249 badarg:
8250 If the process identified by Suspendee is not alive.
8251
8252 badarg:
8253 If the process identified by Suspendee resides on another
8254 node.
8255
8256 badarg:
8257 If OptList is not a proper list of valid Opts.
8258
8259 system_limit:
8260 If the process identified by Suspendee has been suspended
8261 more times by the calling process than can be represented by
8262 the currently used internal data structures. The system
8263 limit is greater than 2,000,000,000 suspends and will never
8264 be lower.
8265
8266 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
8267
8268 Types:
8269
8270 Depth = OldDepth = integer() >= 0
8271
8272 Sets the maximum depth of call stack back-traces in the exit
8273 reason element of 'EXIT' tuples. The flag also limits the stack‐
8274 trace depth returned by process_info item current_stacktrace.
8275
8276 Returns the old value of the flag.
8277
8278 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
8279 OldCpuTopology
8280
8281 Types:
8282
8283 CpuTopology = OldCpuTopology = cpu_topology()
8284 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8285 level_entry() =
8286 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8287 {LevelTag :: level_tag(),
8288 InfoList :: info_list(),
8289 SubLevel :: sub_level()}
8290 level_tag() = core | node | processor | thread
8291 sub_level() =
8292 [LevelEntry :: level_entry()] |
8293 (LogicalCpuId :: {logical, integer() >= 0})
8294 info_list() = []
8295
8296 Warning:
8297 This argument is deprecated. Instead of using this argument, use
8298 command-line argument +sct in erl(1).
8299
8300 When this argument is removed, a final CPU topology to use is
8301 determined at emulator boot time.
8302
8303
8304 Sets the user-defined CpuTopology. The user-defined CPU topology
8305 overrides any automatically detected CPU topology. By passing
8306 undefined as CpuTopology, the system reverts to the CPU topology
8307 automatically detected. The returned value equals the value re‐
8308 turned from erlang:system_info(cpu_topology) before the change
8309 was made.
8310
8311 Returns the old value of the flag.
8312
8313 The CPU topology is used when binding schedulers to logical pro‐
8314 cessors. If schedulers are already bound when the CPU topology
8315 is changed, the schedulers are sent a request to rebind accord‐
8316 ing to the new CPU topology.
8317
8318 The user-defined CPU topology can also be set by passing com‐
8319 mand-line argument +sct to erl(1).
8320
8321 For information on type CpuTopology and more, see erlang:sys‐
8322 tem_info(cpu_topology) as well as command-line flags +sct and
8323 +sbt in erl(1).
8324
8325 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
8326 DirtyCPUSchedulersOnline) ->
8327 OldDirtyCPUSchedulersOnline
8328
8329 Types:
8330
8331 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
8332 teger() >= 1
8333
8334 Sets the number of dirty CPU schedulers online. Range is 1 <=
8335 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
8336 return values of erlang:system_info(dirty_cpu_schedulers) and
8337 erlang:system_info(schedulers_online).
8338
8339 Returns the old value of the flag.
8340
8341 The number of dirty CPU schedulers online can change if the num‐
8342 ber of schedulers online changes. For example, if 12 schedulers
8343 and 6 dirty CPU schedulers are online, and system_flag/2 is used
8344 to set the number of schedulers online to 6, then the number of
8345 dirty CPU schedulers online is automatically decreased by half
8346 as well, down to 3. Similarly, the number of dirty CPU sched‐
8347 ulers online increases proportionally to increases in the number
8348 of schedulers online.
8349
8350 For more information, see erlang:system_info(dirty_cpu_sched‐
8351 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
8352
8353 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
8354 ok | notsup
8355
8356 Types:
8357
8358 Alloc = F = atom()
8359 V = integer()
8360
8361 Sets system flags for erts_alloc(3). Alloc is the allocator to
8362 affect, for example binary_alloc. F is the flag to change and V
8363 is the new value.
8364
8365 Only a subset of all erts_alloc flags can be changed at run
8366 time. This subset is currently only the flag sbct.
8367
8368 Returns ok if the flag was set or notsup if not supported by
8369 erts_alloc.
8370
8371 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
8372
8373 Types:
8374
8375 Number = OldNumber = integer() >= 0
8376
8377 Sets system flag fullsweep_after. Number is a non-negative inte‐
8378 ger indicating how many times generational garbage collections
8379 can be done without forcing a fullsweep collection. The value
8380 applies to new processes, while processes already running are
8381 not affected.
8382
8383 Returns the old value of the flag.
8384
8385 In low-memory systems (especially without virtual memory), set‐
8386 ting the value to 0 can help to conserve memory.
8387
8388 This value can also be set through (OS) environment variable
8389 ERL_FULLSWEEP_AFTER.
8390
8391 erlang:system_flag(Flag :: microstate_accounting, Action) ->
8392 OldState
8393
8394 Types:
8395
8396 Action = true | false | reset
8397 OldState = true | false
8398
8399 Turns on/off microstate accounting measurements. When passing
8400 reset, all counters are reset to 0.
8401
8402 For more information see statistics(microstate_accounting).
8403
8404 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
8405 OldMinHeapSize
8406
8407 Types:
8408
8409 MinHeapSize = OldMinHeapSize = integer() >= 0
8410
8411 Sets the default minimum heap size for processes. The size is
8412 specified in words. The new min_heap_size effects only processes
8413 spawned after the change of min_heap_size has been made.
8414 min_heap_size can be set for individual processes by using
8415 spawn_opt/4 or process_flag/2.
8416
8417 Returns the old value of the flag.
8418
8419 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
8420 OldMinBinVHeapSize
8421
8422 Types:
8423
8424 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
8425
8426 Sets the default minimum binary virtual heap size for processes.
8427 The size is specified in words. The new min_bin_vhheap_size ef‐
8428 fects only processes spawned after the change of
8429 min_bin_vheap_size has been made. min_bin_vheap_size can be set
8430 for individual processes by using spawn_opt/2,3,4 or
8431 process_flag/2.
8432
8433 Returns the old value of the flag.
8434
8435 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
8436 OldMaxHeapSize
8437
8438 Types:
8439
8440 MaxHeapSize = OldMaxHeapSize = max_heap_size()
8441 max_heap_size() =
8442 integer() >= 0 |
8443 #{size => integer() >= 0,
8444 kill => boolean(),
8445 error_logger => boolean()}
8446
8447 Sets the default maximum heap size settings for processes. The
8448 size is specified in words. The new max_heap_size effects only
8449 processes spawned efter the change has been made. max_heap_size
8450 can be set for individual processes using spawn_opt/2,3,4 or
8451 process_flag/2.
8452
8453 Returns the old value of the flag.
8454
8455 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
8456 OldBlockState
8457
8458 Types:
8459
8460 BlockState = block | unblock | block_normal | unblock_normal
8461 OldBlockState = blocked | disabled | enabled
8462
8463 If multi-scheduling is enabled, more than one scheduler thread
8464 is used by the emulator. Multi-scheduling can be blocked in two
8465 different ways. Either all schedulers but one is blocked, or all
8466 normal schedulers but one is blocked. When only normal sched‐
8467 ulers are blocked, dirty schedulers are free to continue to
8468 schedule processes.
8469
8470 If BlockState =:= block, multi-scheduling is blocked. That is,
8471 one and only one scheduler thread will execute. If BlockState
8472 =:= unblock and no one else blocks multi-scheduling, and this
8473 process has blocked only once, multi-scheduling is unblocked.
8474
8475 If BlockState =:= block_normal, normal multi-scheduling is
8476 blocked. That is, only one normal scheduler thread will execute,
8477 but multiple dirty schedulers can execute. If BlockState =:= un‐
8478 block_normal and no one else blocks normal multi-scheduling, and
8479 this process has blocked only once, normal multi-scheduling is
8480 unblocked.
8481
8482 One process can block multi-scheduling and normal multi-schedul‐
8483 ing multiple times. If a process has blocked multiple times, it
8484 must unblock exactly as many times as it has blocked before it
8485 has released its multi-scheduling block. If a process that has
8486 blocked multi-scheduling or normal multi-scheduling exits, it
8487 automatically releases its blocking of multi-scheduling and nor‐
8488 mal multi-scheduling.
8489
8490 The return values are disabled, blocked, blocked_normal, or en‐
8491 abled. The returned value describes the state just after the
8492 call to erlang:system_flag(multi_scheduling, BlockState) has
8493 been made. For information about the return values, see er‐
8494 lang:system_info(multi_scheduling).
8495
8496 Note:
8497 Blocking of multi-scheduling and normal multi-scheduling is nor‐
8498 mally not needed. If you feel that you need to use these fea‐
8499 tures, consider it a few more times again. Blocking multi-sched‐
8500 uling is only to be used as a last resort, as it is most likely
8501 a very inefficient way to solve the problem.
8502
8503
8504 See also erlang:system_info(multi_scheduling), erlang:sys‐
8505 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
8506 tem_info(multi_scheduling_blockers), and erlang:sys‐
8507 tem_info(schedulers).
8508
8509 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
8510 OldBindType
8511
8512 Types:
8513
8514 How = scheduler_bind_type() | default_bind
8515 OldBindType = scheduler_bind_type()
8516 scheduler_bind_type() =
8517 no_node_processor_spread | no_node_thread_spread | no_spread |
8518 processor_spread | spread | thread_spread |
8519 thread_no_node_processor_spread | unbound
8520
8521 Warning:
8522 This argument is deprecated. Instead of using this argument, use
8523 command-line argument +sbt in erl(1). When this argument is re‐
8524 moved, a final scheduler bind type to use is determined at emu‐
8525 lator boot time.
8526
8527
8528 Controls if and how schedulers are bound to logical processors.
8529
8530 When erlang:system_flag(scheduler_bind_type, How) is called, an
8531 asynchronous signal is sent to all schedulers online, causing
8532 them to try to bind or unbind as requested.
8533
8534 Note:
8535 If a scheduler fails to bind, this is often silently ignored, as
8536 it is not always possible to verify valid logical processor
8537 identifiers. If an error is reported, an error event is logged.
8538 To verify that the schedulers have bound as requested, call er‐
8539 lang:system_info(scheduler_bindings).
8540
8541
8542 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
8543 Windows systems, but more systems will be supported in future
8544 releases.
8545
8546 In order for the runtime system to be able to bind schedulers,
8547 the CPU topology must be known. If the runtime system fails to
8548 detect the CPU topology automatically, it can be defined. For
8549 more information on how to define the CPU topology, see command-
8550 line flag +sct in erl(1).
8551
8552 The runtime system does by default not bind schedulers to logi‐
8553 cal processors.
8554
8555 Note:
8556 If the Erlang runtime system is the only OS process binding
8557 threads to logical processors, this improves the performance of
8558 the runtime system. However, if other OS processes (for example,
8559 another Erlang runtime system) also bind threads to logical pro‐
8560 cessors, there can be a performance penalty instead. Sometimes
8561 this performance penalty can be severe. If so, it is recommended
8562 to not bind the schedulers.
8563
8564
8565 Schedulers can be bound in different ways. Argument How deter‐
8566 mines how schedulers are bound and can be any of the following:
8567
8568 unbound:
8569 Same as command-line argument +sbt u in erl(1).
8570
8571 no_spread:
8572 Same as command-line argument +sbt ns in erl(1).
8573
8574 thread_spread:
8575 Same as command-line argument +sbt ts in erl(1).
8576
8577 processor_spread:
8578 Same as command-line argument +sbt ps in erl(1).
8579
8580 spread:
8581 Same as command-line argument +sbt s in erl(1).
8582
8583 no_node_thread_spread:
8584 Same as command-line argument +sbt nnts in erl(1).
8585
8586 no_node_processor_spread:
8587 Same as command-line argument +sbt nnps in erl(1).
8588
8589 thread_no_node_processor_spread:
8590 Same as command-line argument +sbt tnnps in erl(1).
8591
8592 default_bind:
8593 Same as command-line argument +sbt db in erl(1).
8594
8595 The returned value equals How before flag scheduler_bind_type
8596 was changed.
8597
8598 Failures:
8599
8600 notsup:
8601 If binding of schedulers is not supported.
8602
8603 badarg:
8604 If How is not one of the documented alternatives.
8605
8606 badarg:
8607 If CPU topology information is unavailable.
8608
8609 The scheduler bind type can also be set by passing command-line
8610 argument +sbt to erl(1).
8611
8612 For more information, see erlang:system_info(sched‐
8613 uler_bind_type), erlang:system_info(scheduler_bindings), as well
8614 as command-line flags +sbt and +sct in erl(1).
8615
8616 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
8617 OldBoolean
8618
8619 Types:
8620
8621 Boolean = OldBoolean = boolean()
8622
8623 Turns on or off scheduler wall time measurements.
8624
8625 For more information, see statistics(scheduler_wall_time).
8626
8627 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
8628 OldSchedulersOnline
8629
8630 Types:
8631
8632 SchedulersOnline = OldSchedulersOnline = integer() >= 1
8633
8634 Sets the number of schedulers online. Range is 1 <= Scheduler‐
8635 sOnline <= erlang:system_info(schedulers).
8636
8637 Returns the old value of the flag.
8638
8639 If the emulator was built with support for dirty schedulers,
8640 changing the number of schedulers online can also change the
8641 number of dirty CPU schedulers online. For example, if 12 sched‐
8642 ulers and 6 dirty CPU schedulers are online, and system_flag/2
8643 is used to set the number of schedulers online to 6, then the
8644 number of dirty CPU schedulers online is automatically decreased
8645 by half as well, down to 3. Similarly, the number of dirty CPU
8646 schedulers online increases proportionally to increases in the
8647 number of schedulers online.
8648
8649 For more information, see erlang:system_info(schedulers) and er‐
8650 lang:system_info(schedulers_online).
8651
8652 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
8653
8654 Types:
8655
8656 Logger = PrevLogger = logger | undefined | pid()
8657
8658 Sets the process that will receive the logging messages gener‐
8659 ated by ERTS. If set to undefined, all logging messages gener‐
8660 ated by ERTS will be dropped. The messages will be in the for‐
8661 mat:
8662
8663 {log,Level,Format,ArgList,Metadata} where
8664
8665 Level = atom(),
8666 Format = string(),
8667 ArgList = list(term()),
8668 Metadata = #{ pid => pid(),
8669 group_leader => pid(),
8670 time := logger:timestamp(),
8671 error_logger := #{ emulator := true, tag := atom() }
8672
8673
8674 If the system_logger process dies, this flag will be reset to
8675 logger.
8676
8677 The default is the process named logger.
8678
8679 Returns the old value of the flag.
8680
8681 Note:
8682 This function is designed to be used by the KERNEL logger. Be
8683 careful if you change it to something else as log messages may
8684 be lost. If you want to intercept emulator log messages, do it
8685 by adding a specialized handler to the KERNEL logger.
8686
8687
8688 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
8689
8690 Types:
8691
8692 TCW = OldTCW = integer() >= 0
8693
8694 Sets the value of the node trace control word to TCW, which is
8695 to be an unsigned integer. For more information, see function
8696 set_tcw in section "Match Specifications in Erlang" in the
8697 User's Guide.
8698
8699 Returns the old value of the flag.
8700
8701 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
8702 OldState
8703
8704 Types:
8705
8706 OldState = preliminary | final | volatile
8707
8708 Finalizes the time offset when single time warp mode is used. If
8709 another time warp mode is used, the time offset state is left
8710 unchanged.
8711
8712 Returns the old state identifier, that is:
8713
8714 * If preliminary is returned, finalization was performed and
8715 the time offset is now final.
8716
8717 * If final is returned, the time offset was already in the fi‐
8718 nal state. This either because another erlang:sys‐
8719 tem_flag(time_offset, finalize) call or because no time warp
8720 mode is used.
8721
8722 * If volatile is returned, the time offset cannot be finalized
8723 because multi-time warp mode is used.
8724
8725 erlang:system_info(Item :: version) -> string()
8726
8727 Returns information about the current system. The documentation
8728 of this function is broken into the following sections in order
8729 to make it easier to navigate.
8730
8731 Memory Allocation:
8732 allocated_areas, allocator, alloc_util_allocators, alloca‐
8733 tor_sizes
8734
8735 CPU Topology:
8736 cpu_topology, logical_processors, update_cpu_info
8737
8738 Process Information:
8739 fullsweep_after, garbage_collection, heap_sizes, heap_type,
8740 max_heap_size, message_queue_data, min_heap_size,
8741 min_bin_vheap_size, procs
8742
8743 System Limits:
8744 atom_count, atom_limit, ets_count, ets_limit, port_count,
8745 port_limit, process_count, process_limit
8746
8747 System Time:
8748 end_time, os_monotonic_time_source, os_system_time_source,
8749 start_time, time_correction, time_offset, time_warp_mode,
8750 tolerant_timeofday
8751
8752 Scheduler Information:
8753 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
8754 dirty_io_schedulers, multi_scheduling, multi_schedul‐
8755 ing_blockers, normal_multi_scheduling_blockers, sched‐
8756 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
8757 ulers, smp_support, threads, thread_pool_size
8758
8759 Distribution Information:
8760 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
8761 dist_ctrl
8762
8763 System Information:
8764 c_compiler_used, check_io, compat_rel, debug_compiled,
8765 driver_version, dynamic_trace, dynamic_trace_probes,
8766 emu_flavor, emu_type, info, kernel_poll, loaded, machine,
8767 modified_timing_level, nif_version, otp_release, port_paral‐
8768 lelism, system_architecture, system_logger, system_version,
8769 trace_control_word, version, wordsize
8770
8771 erlang:system_info(Item :: allocated_areas) -> [tuple()]
8772
8773 erlang:system_info(Item :: allocator) ->
8774 {Allocator, Version, Features, Settings}
8775
8776 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
8777
8778 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
8779
8780 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
8781
8782 Types:
8783
8784 Allocator = undefined | glibc
8785 Version = [integer() >= 0]
8786 Features = [atom()]
8787 Settings =
8788 [{Subsystem :: atom(),
8789 [{Parameter :: atom(), Value :: term()}]}]
8790 Alloc = atom()
8791
8792 Returns various information about the memory allocators of the
8793 current system (emulator) as specified by Item:
8794
8795 allocated_areas:
8796 Returns a list of tuples with information about miscella‐
8797 neous allocated memory areas.
8798
8799 Each tuple contains an atom describing the type of memory as
8800 first element and the amount of allocated memory in bytes as
8801 second element. When information about allocated and used
8802 memory is present, also a third element is present, contain‐
8803 ing the amount of used memory in bytes.
8804
8805 erlang:system_info(allocated_areas) is intended for debug‐
8806 ging, and the content is highly implementation-dependent.
8807 The content of the results therefore changes when needed
8808 without prior notice.
8809
8810 Notice that the sum of these values is not the total amount
8811 of memory allocated by the emulator. Some values are part of
8812 other values, and some memory areas are not part of the re‐
8813 sult. For information about the total amount of memory allo‐
8814 cated by the emulator, see erlang:memory/0,1.
8815
8816 allocator:
8817 Returns {Allocator, Version, Features, Settings, where:
8818
8819 * Allocator corresponds to the malloc() implementation used.
8820 If Allocator equals undefined, the malloc() implementation
8821 used cannot be identified. glibc can be identified.
8822
8823 * Version is a list of integers (but not a string) repre‐
8824 senting the version of the malloc() implementation used.
8825
8826 * Features is a list of atoms representing the allocation
8827 features used.
8828
8829 * Settings is a list of subsystems, their configurable pa‐
8830 rameters, and used values. Settings can differ between
8831 different combinations of platforms, allocators, and allo‐
8832 cation features. Memory sizes are given in bytes.
8833
8834 See also "System Flags Effecting erts_alloc" in erts_al‐
8835 loc(3).
8836
8837 {allocator, Alloc}:
8838 Returns information about the specified allocator. As from
8839 ERTS 5.6.1, the return value is a list of {instance, Instan‐
8840 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
8841 formation about a specific instance of the allocator. If Al‐
8842 loc is not a recognized allocator, undefined is returned. If
8843 Alloc is disabled, false is returned.
8844
8845 Notice that the information returned is highly implementa‐
8846 tion-dependent and can be changed or removed at any time
8847 without prior notice. It was initially intended as a tool
8848 when developing new allocators, but as it can be of interest
8849 for others it has been briefly documented.
8850
8851 The recognized allocators are listed in erts_alloc(3). In‐
8852 formation about super carriers can be obtained from ERTS 8.0
8853 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
8854 turned list when calling with {allocator, mseg_alloc} also
8855 includes an {erts_mmap, _} tuple as one element in the list.
8856
8857 After reading the erts_alloc(3) documentation, the returned
8858 information more or less speaks for itself, but it can be
8859 worth explaining some things. Call counts are presented by
8860 two values, the first value is giga calls, and the second
8861 value is calls. mbcs and sbcs denote multi-block carriers,
8862 and single-block carriers, respectively. Sizes are presented
8863 in bytes. When a size is not presented, it is the amount of
8864 something. Sizes and amounts are often presented by three
8865 values:
8866
8867 * The first is the current value.
8868
8869 * The second is the maximum value since the last call to er‐
8870 lang:system_info({allocator, Alloc}).
8871
8872 * The third is the maximum value since the emulator was
8873 started.
8874
8875 If only one value is present, it is the current value.
8876 fix_alloc memory block types are presented by two values.
8877 The first value is the memory pool size and the second value
8878 is the used memory size.
8879
8880 alloc_util_allocators:
8881 Returns a list of the names of all allocators using the ERTS
8882 internal alloc_util framework as atoms. For more informa‐
8883 tion, see section The alloc_util framework in erts_alloc(3).
8884
8885 {allocator_sizes, Alloc}:
8886 Returns various size information for the specified alloca‐
8887 tor. The information returned is a subset of the information
8888 returned by erlang:system_info({allocator, Alloc}).
8889
8890 erlang:system_info(Item :: cpu_topology) -> CpuTopology
8891
8892 erlang:system_info(Item ::
8893 {cpu_topology, defined | detected | used}) ->
8894 CpuTopology
8895
8896 erlang:system_info(Item ::
8897 logical_processors |
8898 logical_processors_available |
8899 logical_processors_online) ->
8900 unknown | integer() >= 1
8901
8902 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
8903
8904 Types:
8905
8906 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8907 All LevelEntrys of a list must contain the same LevelTag,
8908 except on the top level where both node and processor‐
8909 LevelTags can coexist.
8910 level_entry() =
8911 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8912 {LevelTag :: level_tag(),
8913 InfoList :: info_list(),
8914 SubLevel :: sub_level()}
8915 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
8916 level_tag() = core | node | processor | thread
8917 More LevelTags can be introduced in a future release.
8918 sub_level() =
8919 [LevelEntry :: level_entry()] |
8920 (LogicalCpuId :: {logical, integer() >= 0})
8921 info_list() = []
8922 The info_list() can be extended in a future release.
8923
8924 Returns various information about the CPU topology of the cur‐
8925 rent system (emulator) as specified by Item:
8926
8927 cpu_topology:
8928 Returns the CpuTopology currently used by the emulator. The
8929 CPU topology is used when binding schedulers to logical pro‐
8930 cessors. The CPU topology used is the user-defined CPU
8931 topology, if such exists, otherwise the automatically de‐
8932 tected CPU topology, if such exists. If no CPU topology ex‐
8933 ists, undefined is returned.
8934
8935 node refers to Non-Uniform Memory Access (NUMA) nodes.
8936 thread refers to hardware threads (for example, Intel hyper-
8937 threads).
8938
8939 A level in term CpuTopology can be omitted if only one entry
8940 exists and InfoList is empty.
8941
8942 thread can only be a sublevel to core. core can be a sub‐
8943 level to processor or node. processor can be on the top
8944 level or a sublevel to node. node can be on the top level or
8945 a sublevel to processor. That is, NUMA nodes can be proces‐
8946 sor internal or processor external. A CPU topology can con‐
8947 sist of a mix of processor internal and external NUMA nodes,
8948 as long as each logical CPU belongs to one NUMA node. Cache
8949 hierarchy is not part of the CpuTopology type, but will be
8950 in a future release. Other things can also make it into the
8951 CPU topology in a future release. So, expect the CpuTopology
8952 type to change.
8953
8954 {cpu_topology, defined}:
8955
8956
8957 Returns the user-defined CpuTopology. For more information,
8958 see command-line flag +sct in erl(1) and argument cpu_topol‐
8959 ogy.
8960
8961 {cpu_topology, detected}:
8962
8963
8964 Returns the automatically detected CpuTopologyy. The emula‐
8965 tor detects the CPU topology on some newer Linux, Solaris,
8966 FreeBSD, and Windows systems. On Windows system with more
8967 than 32 logical processors, the CPU topology is not de‐
8968 tected.
8969
8970 For more information, see argument cpu_topology.
8971
8972 {cpu_topology, used}:
8973 Returns CpuTopology used by the emulator. For more informa‐
8974 tion, see argument cpu_topology.
8975
8976 logical_processors:
8977 Returns the detected number of logical processors configured
8978 in the system. The return value is either an integer, or the
8979 atom unknown if the emulator cannot detect the configured
8980 logical processors.
8981
8982 logical_processors_available:
8983 Returns the detected number of logical processors available
8984 to the Erlang runtime system. The return value is either an
8985 integer, or the atom unknown if the emulator cannot detect
8986 the available logical processors. The number of available
8987 logical processors is less than or equal to the number of
8988 logical processors online.
8989
8990 logical_processors_online:
8991 Returns the detected number of logical processors online on
8992 the system. The return value is either an integer, or the
8993 atom unknown if the emulator cannot detect logical proces‐
8994 sors online. The number of logical processors online is less
8995 than or equal to the number of logical processors config‐
8996 ured.
8997
8998 cpu_quota:
8999 Returns the detected CPU quota the emulator is limited by.
9000 The return value is an integer saying how many processors'
9001 worth of runtime we get (between 1 and the number of logical
9002 processors), or the atom unknown if the emulator cannot de‐
9003 tect a quota.
9004
9005 update_cpu_info:
9006 The runtime system rereads the CPU information available and
9007 updates its internally stored information about the detected
9008 CPU topology and the number of logical processors config‐
9009 ured, online, available, and cpu quota.
9010
9011 If the CPU information has changed since the last time it
9012 was read, the atom changed is returned, otherwise the atom
9013 unchanged. If the CPU information has changed, you probably
9014 want to adjust the number of schedulers online. You typi‐
9015 cally want to have as many schedulers online as logical pro‐
9016 cessors available.
9017
9018 erlang:system_info(Item :: fullsweep_after) ->
9019 {fullsweep_after, integer() >= 0}
9020
9021 erlang:system_info(Item :: garbage_collection) ->
9022 [{atom(), integer()}]
9023
9024 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
9025
9026 erlang:system_info(Item :: heap_type) -> private
9027
9028 erlang:system_info(Item :: max_heap_size) ->
9029 {max_heap_size,
9030 MaxHeapSize :: max_heap_size()}
9031
9032 erlang:system_info(Item :: message_queue_data) ->
9033 message_queue_data()
9034
9035 erlang:system_info(Item :: min_heap_size) ->
9036 {min_heap_size,
9037 MinHeapSize :: integer() >= 1}
9038
9039 erlang:system_info(Item :: min_bin_vheap_size) ->
9040 {min_bin_vheap_size,
9041 MinBinVHeapSize :: integer() >= 1}
9042
9043 erlang:system_info(Item :: procs) -> binary()
9044
9045 Types:
9046
9047 message_queue_data() = off_heap | on_heap
9048 max_heap_size() =
9049 integer() >= 0 |
9050 #{size => integer() >= 0,
9051 kill => boolean(),
9052 error_logger => boolean()}
9053
9054 Returns information about the default process heap settings:
9055
9056 fullsweep_after:
9057 Returns {fullsweep_after, integer() >= 0}, which is the
9058 fullsweep_after garbage collection setting used by default.
9059 For more information, see garbage_collection described be‐
9060 low.
9061
9062 garbage_collection:
9063 Returns a list describing the default garbage collection
9064 settings. A process spawned on the local node by a spawn or
9065 spawn_link uses these garbage collection settings. The de‐
9066 fault settings can be changed by using erlang:system_flag/2.
9067 spawn_opt/2,3,4 can spawn a process that does not use the
9068 default settings.
9069
9070 heap_sizes:
9071 Returns a list of integers representing valid heap sizes in
9072 words. All Erlang heaps are sized from sizes in this list.
9073
9074 heap_type:
9075 Returns the heap type used by the current emulator. One heap
9076 type exists:
9077
9078 private:
9079 Each process has a heap reserved for its use and no ref‐
9080 erences between heaps of different processes are allowed.
9081 Messages passed between processes are copied between
9082 heaps.
9083
9084 max_heap_size:
9085 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
9086 the current system-wide maximum heap size settings for
9087 spawned processes. This setting can be set using the com‐
9088 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
9089 also be changed at runtime using erlang:sys‐
9090 tem_flag(max_heap_size, MaxHeapSize). For more details about
9091 the max_heap_size process flag, see
9092 process_flag(max_heap_size, MaxHeapSize).
9093
9094 message_queue_data:
9095 Returns the default value of the message_queue_data process
9096 flag, which can be either off_heap or on_heap. The default
9097 value is set by the command-line argument +hmqd in erl(1).
9098 For more information, see the documentation of
9099 process_flag(message_queue_data, MQD).
9100
9101 min_heap_size:
9102 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
9103 the current system-wide minimum heap size for spawned pro‐
9104 cesses.
9105
9106 min_bin_vheap_size:
9107 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
9108 VHeapSize is the current system-wide minimum binary virtual
9109 heap size for spawned processes.
9110
9111 procs:
9112 Returns a binary containing a string of process and port in‐
9113 formation formatted as in Erlang crash dumps. For more in‐
9114 formation, see section How to interpret the Erlang crash
9115 dumps in the User's Guide.
9116
9117 erlang:system_info(Item :: atom_count) -> integer() >= 1
9118
9119 erlang:system_info(Item :: atom_limit) -> integer() >= 1
9120
9121 erlang:system_info(Item :: ets_count) -> integer() >= 1
9122
9123 erlang:system_info(Item :: ets_limit) -> integer() >= 1
9124
9125 erlang:system_info(Item :: port_count) -> integer() >= 0
9126
9127 erlang:system_info(Item :: port_limit) -> integer() >= 1
9128
9129 erlang:system_info(Item :: process_count) -> integer() >= 1
9130
9131 erlang:system_info(Item :: process_limit) -> integer() >= 1
9132
9133 Returns information about the current system (emulator) limits
9134 as specified by Item:
9135
9136 atom_count:
9137 Returns the number of atoms currently existing at the local
9138 node. The value is given as an integer.
9139
9140 atom_limit:
9141 Returns the maximum number of atoms allowed. This limit can
9142 be increased at startup by passing command-line flag +t to
9143 erl(1).
9144
9145 ets_count:
9146 Returns the number of ETS tables currently existing at the
9147 local node.
9148
9149 ets_limit:
9150 Returns the limit for number of ETS tables. This limit is
9151 partially obsolete and number of tables are only limited by
9152 available memory.
9153
9154 port_count:
9155 Returns the number of ports currently existing at the local
9156 node. The value is given as an integer. This is the same
9157 value as returned by length(erlang:ports()), but more effi‐
9158 cient.
9159
9160 port_limit:
9161 Returns the maximum number of simultaneously existing ports
9162 at the local node as an integer. This limit can be config‐
9163 ured at startup by using command-line flag +Q in erl(1).
9164
9165 process_count:
9166 Returns the number of processes currently existing at the
9167 local node. The value is given as an integer. This is the
9168 same value as returned by length(processes()), but more ef‐
9169 ficient.
9170
9171 process_limit:
9172 Returns the maximum number of simultaneously existing pro‐
9173 cesses at the local node. The value is given as an integer.
9174 This limit can be configured at startup by using command-
9175 line flag +P in erl(1).
9176
9177 erlang:system_info(Item :: end_time) -> integer() >= 0
9178
9179 erlang:system_info(Item :: os_monotonic_time_source) ->
9180 [{atom(), term()}]
9181
9182 erlang:system_info(Item :: os_system_time_source) ->
9183 [{atom(), term()}]
9184
9185 erlang:system_info(Item :: start_time) -> integer()
9186
9187 erlang:system_info(Item :: time_correction) -> true | false
9188
9189 erlang:system_info(Item :: time_offset) ->
9190 preliminary | final | volatile
9191
9192 erlang:system_info(Item :: time_warp_mode) ->
9193 no_time_warp | single_time_warp |
9194 multi_time_warp
9195
9196 erlang:system_info(Item :: tolerant_timeofday) ->
9197 enabled | disabled
9198
9199 Returns information about the current system (emulator) time as
9200 specified by Item:
9201
9202 end_time:
9203 The last Erlang monotonic time in native time unit that can
9204 be represented internally in the current Erlang runtime sys‐
9205 tem instance. The time between the start time and the end
9206 time is at least a quarter of a millennium.
9207
9208 os_monotonic_time_source:
9209 Returns a list containing information about the source of OS
9210 monotonic time that is used by the runtime system.
9211
9212 If [] is returned, no OS monotonic time is available. The
9213 list contains two-tuples with Keys as first element, and
9214 Values as second element. The order of these tuples is unde‐
9215 fined. The following tuples can be part of the list, but
9216 more tuples can be introduced in the future:
9217
9218 {function, Function}:
9219 Function is the name of the function used. This tuple al‐
9220 ways exists if OS monotonic time is available to the run‐
9221 time system.
9222
9223 {clock_id, ClockId}:
9224 This tuple only exists if Function can be used with dif‐
9225 ferent clocks. ClockId corresponds to the clock identifier
9226 used when calling Function.
9227
9228 {resolution, OsMonotonicTimeResolution}:
9229 Highest possible resolution of current OS monotonic time
9230 source as parts per second. If no resolution information
9231 can be retrieved from the OS, OsMonotonicTimeResolution is
9232 set to the resolution of the time unit of Functions return
9233 value. That is, the actual resolution can be lower than
9234 OsMonotonicTimeResolution. Notice that the resolution does
9235 not say anything about the accuracy or whether the pre‐
9236 cision aligns with the resolution. You do, however, know
9237 that the precision is not better than OsMonotonicTimeReso‐
9238 lution.
9239
9240 {extended, Extended}:
9241 Extended equals yes if the range of time values has been
9242 extended; otherwise Extended equals no. The range must be
9243 extended if Function returns values that wrap fast. This
9244 typically is the case when the return value is a 32-bit
9245 value.
9246
9247 {parallel, Parallel}:
9248 Parallel equals yes if Function is called in parallel from
9249 multiple threads. If it is not called in parallel, because
9250 calls must be serialized, Parallel equals no.
9251
9252 {time, OsMonotonicTime}:
9253 OsMonotonicTime equals current OS monotonic time in native
9254 time unit.
9255
9256 os_system_time_source:
9257 Returns a list containing information about the source of OS
9258 system time that is used by the runtime system.
9259
9260 The list contains two-tuples with Keys as first element, and
9261 Values as second element. The order of these tuples is unde‐
9262 fined. The following tuples can be part of the list, but
9263 more tuples can be introduced in the future:
9264
9265 {function, Function}:
9266 Function is the name of the funcion used.
9267
9268 {clock_id, ClockId}:
9269 Exists only if Function can be used with different clocks.
9270 ClockId corresponds to the clock identifier used when
9271 calling Function.
9272
9273 {resolution, OsSystemTimeResolution}:
9274 Highest possible resolution of current OS system time
9275 source as parts per second. If no resolution information
9276 can be retrieved from the OS, OsSystemTimeResolution is
9277 set to the resolution of the time unit of Functions return
9278 value. That is, the actual resolution can be lower than
9279 OsSystemTimeResolution. Notice that the resolution does
9280 not say anything about the accuracy or whether the pre‐
9281 cision do align with the resolution. You do, however, know
9282 that the precision is not better than OsSystemTimeResolu‐
9283 tion.
9284
9285 {parallel, Parallel}:
9286 Parallel equals yes if Function is called in parallel from
9287 multiple threads. If it is not called in parallel, because
9288 calls needs to be serialized, Parallel equals no.
9289
9290 {time, OsSystemTime}:
9291 OsSystemTime equals current OS system time in native time
9292 unit.
9293
9294 start_time:
9295 The Erlang monotonic time in native time unit at the time
9296 when current Erlang runtime system instance started.
9297
9298 See also erlang:system_info(end_time).
9299
9300 time_correction:
9301 Returns a boolean value indicating whether time correction
9302 is enabled or not.
9303
9304 time_offset:
9305 Returns the state of the time offset:
9306
9307 preliminary:
9308 The time offset is preliminary, and will be changed and
9309 finalized later. The preliminary time offset is used dur‐
9310 ing the preliminary phase of the single time warp mode.
9311
9312 final:
9313 The time offset is final. This either because no time
9314 warp mode is used, or because the time offset have been
9315 finalized when single time warp mode is used.
9316
9317 volatile:
9318 The time offset is volatile. That is, it can change at any
9319 time. This is because multi-time warp mode is used.
9320
9321 time_warp_mode:
9322 Returns a value identifying the time warp mode that is
9323 used:
9324
9325 no_time_warp:
9326 The no time warp mode is used.
9327
9328 single_time_warp:
9329 The single time warp mode is used.
9330
9331 multi_time_warp:
9332 The multi-time warp mode is used.
9333
9334 tolerant_timeofday:
9335 Returns whether a pre ERTS 7.0 backwards compatible compen‐
9336 sation for sudden changes of system time is enabled or dis‐
9337 abled. Such compensation is enabled when the time offset is
9338 final, and time correction is enabled.
9339
9340 erlang:system_info(Item :: dirty_cpu_schedulers) ->
9341 integer() >= 0
9342
9343 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
9344 integer() >= 0
9345
9346 erlang:system_info(Item :: dirty_io_schedulers) ->
9347 integer() >= 0
9348
9349 erlang:system_info(Item :: multi_scheduling) ->
9350 disabled | blocked | blocked_normal |
9351 enabled
9352
9353 erlang:system_info(Item :: multi_scheduling_blockers) ->
9354 [Pid :: pid()]
9355
9356 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
9357 [Pid :: pid()]
9358
9359 erlang:system_info(Item :: scheduler_bind_type) ->
9360 spread | processor_spread | thread_spread |
9361 thread_no_node_processor_spread |
9362 no_node_processor_spread |
9363 no_node_thread_spread | no_spread | unbound
9364
9365 erlang:system_info(Item :: scheduler_bindings) -> tuple()
9366
9367 erlang:system_info(Item :: scheduler_id) ->
9368 SchedulerId :: integer() >= 1
9369
9370 erlang:system_info(Item :: schedulers | schedulers_online) ->
9371 integer() >= 1
9372
9373 erlang:system_info(Item :: smp_support) -> boolean()
9374
9375 erlang:system_info(Item :: threads) -> boolean()
9376
9377 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
9378
9379 Returns information about schedulers, scheduling and threads in
9380 the current system as specified by Item:
9381
9382 dirty_cpu_schedulers:
9383 Returns the number of dirty CPU scheduler threads used by
9384 the emulator. Dirty CPU schedulers execute CPU-bound native
9385 functions, such as NIFs, linked-in driver code, and BIFs
9386 that cannot be managed cleanly by the normal emulator sched‐
9387 ulers.
9388
9389 The number of dirty CPU scheduler threads is determined at
9390 emulator boot time and cannot be changed after that. How‐
9391 ever, the number of dirty CPU scheduler threads online can
9392 be changed at any time. The number of dirty CPU schedulers
9393 can be set at startup by passing command-line flag +SDcpu or
9394 +SDPcpu in erl(1).
9395
9396 See also erlang:system_flag(dirty_cpu_schedulers_online,
9397 DirtyCPUSchedulersOnline), erlang:sys‐
9398 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
9399 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9400 ulers), erlang:system_info(schedulers_online), and er‐
9401 lang:system_flag(schedulers_online, SchedulersOnline).
9402
9403 dirty_cpu_schedulers_online:
9404 Returns the number of dirty CPU schedulers online. The re‐
9405 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
9406 where N is the smallest of the return values of erlang:sys‐
9407 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
9408 ulers_online).
9409
9410 The number of dirty CPU schedulers online can be set at
9411 startup by passing command-line flag +SDcpu in erl(1).
9412
9413 For more information, see erlang:sys‐
9414 tem_info(dirty_cpu_schedulers), erlang:sys‐
9415 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9416 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
9417 ulers_online, DirtyCPUSchedulersOnline).
9418
9419 dirty_io_schedulers:
9420 Returns the number of dirty I/O schedulers as an integer.
9421 Dirty I/O schedulers execute I/O-bound native functions,
9422 such as NIFs and linked-in driver code, which cannot be man‐
9423 aged cleanly by the normal emulator schedulers.
9424
9425 This value can be set at startup by passing command-line ar‐
9426 gument +SDio in erl(1).
9427
9428 For more information, see erlang:sys‐
9429 tem_info(dirty_cpu_schedulers), erlang:sys‐
9430 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
9431 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
9432 line).
9433
9434 multi_scheduling:
9435 Returns one of the following:
9436
9437 disabled:
9438 The emulator has been started with only one scheduler
9439 thread.
9440
9441 blocked:
9442 The emulator has more than one scheduler thread, but all
9443 scheduler threads except one are blocked. That is, only
9444 one scheduler thread schedules Erlang processes and exe‐
9445 cutes Erlang code.
9446
9447 blocked_normal:
9448 The emulator has more than one scheduler thread, but all
9449 normal scheduler threads except one are blocked. Notice
9450 that dirty schedulers are not blocked, and can schedule
9451 Erlang processes and execute native code.
9452
9453 enabled:
9454 The emulator has more than one scheduler thread, and no
9455 scheduler threads are blocked. That is, all available
9456 scheduler threads schedule Erlang processes and execute
9457 Erlang code.
9458
9459 See also erlang:system_flag(multi_scheduling, BlockState),
9460 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
9461 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9462 tem_info(schedulers).
9463
9464 multi_scheduling_blockers:
9465 Returns a list of Pids when multi-scheduling is blocked,
9466 otherwise the empty list is returned. The Pids in the list
9467 represent all the processes currently blocking multi-sched‐
9468 uling. A Pid occurs only once in the list, even if the cor‐
9469 responding process has blocked multiple times.
9470
9471 See also erlang:system_flag(multi_scheduling, BlockState),
9472 erlang:system_info(multi_scheduling), erlang:sys‐
9473 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9474 tem_info(schedulers).
9475
9476 normal_multi_scheduling_blockers:
9477 Returns a list of Pids when normal multi-scheduling is
9478 blocked (that is, all normal schedulers but one is blocked),
9479 otherwise the empty list is returned. The Pids in the list
9480 represent all the processes currently blocking normal multi-
9481 scheduling. A Pid occurs only once in the list, even if the
9482 corresponding process has blocked multiple times.
9483
9484 See also erlang:system_flag(multi_scheduling, BlockState),
9485 erlang:system_info(multi_scheduling), erlang:sys‐
9486 tem_info(multi_scheduling_blockers), and erlang:sys‐
9487 tem_info(schedulers).
9488
9489 scheduler_bind_type:
9490 Returns information about how the user has requested sched‐
9491 ulers to be bound or not bound.
9492
9493 Notice that although a user has requested schedulers to be
9494 bound, they can silently have failed to bind. To inspect the
9495 scheduler bindings, call erlang:system_info(scheduler_bind‐
9496 ings).
9497
9498 For more information, see command-line argument +sbt in
9499 erl(1) and erlang:system_info(scheduler_bindings).
9500
9501 scheduler_bindings:
9502 Returns information about the currently used scheduler bind‐
9503 ings.
9504
9505 A tuple of a size equal to erlang:system_info(schedulers) is
9506 returned. The tuple elements are integers or the atom un‐
9507 bound. Logical processor identifiers are represented as in‐
9508 tegers. The Nth element of the tuple equals the current
9509 binding for the scheduler with the scheduler identifier
9510 equal to N. For example, if the schedulers are bound, ele‐
9511 ment(erlang:system_info(scheduler_id), erlang:sys‐
9512 tem_info(scheduler_bindings)) returns the identifier of the
9513 logical processor that the calling process is executing on.
9514
9515 Notice that only schedulers online can be bound to logical
9516 processors.
9517
9518 For more information, see command-line argument +sbt in
9519 erl(1) and erlang:system_info(schedulers_online).
9520
9521 scheduler_id:
9522 Returns the scheduler ID (SchedulerId) of the scheduler
9523 thread that the calling process is executing on. SchedulerId
9524 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
9525 tem_info(schedulers).
9526
9527 See also erlang:system_info(schedulers).
9528
9529 schedulers:
9530 Returns the number of scheduler threads used by the emula‐
9531 tor. Scheduler threads online schedules Erlang processes and
9532 Erlang ports, and execute Erlang code and Erlang linked-in
9533 driver code.
9534
9535 The number of scheduler threads is determined at emulator
9536 boot time and cannot be changed later. However, the number
9537 of schedulers online can be changed at any time.
9538
9539 See also erlang:system_flag(schedulers_online, SchedulersOn‐
9540 line), erlang:system_info(schedulers_online), erlang:sys‐
9541 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
9542 BlockState), erlang:system_info(multi_scheduling), er‐
9543 lang:system_info(normal_multi_scheduling_blockers) and er‐
9544 lang:system_info(multi_scheduling_blockers).
9545
9546 schedulers_online:
9547 Returns the number of schedulers online. The scheduler iden‐
9548 tifiers of schedulers online satisfy the relationship 1 <=
9549 SchedulerId <= erlang:system_info(schedulers_online).
9550
9551 For more information, see erlang:system_info(schedulers) and
9552 erlang:system_flag(schedulers_online, SchedulersOnline).
9553
9554 smp_support:
9555 Returns true.
9556
9557 threads:
9558 Returns true.
9559
9560 thread_pool_size:
9561
9562
9563 Returns the number of async threads in the async thread pool
9564 used for asynchronous driver calls
9565 (erl_driver:driver_async()). The value is given as an inte‐
9566 ger.
9567
9568 erlang:system_info(Item :: creation) -> integer()
9569
9570 erlang:system_info(Item :: delayed_node_table_gc) ->
9571 infinity | integer() >= 0
9572
9573 erlang:system_info(Item :: dist) -> binary()
9574
9575 erlang:system_info(Item :: dist_buf_busy_limit) ->
9576 integer() >= 0
9577
9578 erlang:system_info(Item :: dist_ctrl) ->
9579 {Node :: node(),
9580 ControllingEntity :: port() | pid()}
9581
9582 Returns information about Erlang Distribution in the current
9583 system as specified by Item:
9584
9585 creation:
9586 Returns the creation of the local node as an integer. The
9587 creation is changed when a node is restarted. The creation
9588 of a node is stored in process identifiers, port identi‐
9589 fiers, and references. This makes it (to some extent) possi‐
9590 ble to distinguish between identifiers from different incar‐
9591 nations of a node. The valid creations are integers in the
9592 range 1..3, but this will probably change in a future re‐
9593 lease. If the node is not alive, 0 is returned.
9594
9595 delayed_node_table_gc:
9596 Returns the amount of time in seconds garbage collection of
9597 an entry in a node table is delayed. This limit can be set
9598 on startup by passing command-line flag +zdntgc to erl(1).
9599 For more information, see the documentation of the command-
9600 line flag.
9601
9602 dist:
9603 Returns a binary containing a string of distribution infor‐
9604 mation formatted as in Erlang crash dumps. For more informa‐
9605 tion, see section How to interpret the Erlang crash dumps
9606 in the User's Guide.
9607
9608 dist_buf_busy_limit:
9609 Returns the value of the distribution buffer busy limit in
9610 bytes. This limit can be set at startup by passing command-
9611 line flag +zdbbl to erl(1).
9612
9613 dist_ctrl:
9614 Returns a list of tuples {Node, ControllingEntity}, one en‐
9615 try for each connected remote node. Node is the node name
9616 and ControllingEntity is the port or process identifier re‐
9617 sponsible for the communication to that node. More specifi‐
9618 cally, ControllingEntity for nodes connected through TCP/IP
9619 (the normal case) is the socket used in communication with
9620 the specific node.
9621
9622 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
9623
9624 erlang:system_info(Item :: check_io) -> [term()]
9625
9626 erlang:system_info(Item :: compat_rel) -> integer()
9627
9628 erlang:system_info(Item :: debug_compiled) -> boolean()
9629
9630 erlang:system_info(Item :: driver_version) -> string()
9631
9632 erlang:system_info(Item :: dynamic_trace) ->
9633 none | dtrace | systemtap
9634
9635 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
9636
9637 erlang:system_info(Item :: emu_flavor) -> emu | jit
9638
9639 erlang:system_info(Item :: emu_type) ->
9640 opt | debug | gcov | valgrind | gprof |
9641 lcnt | frmptr
9642
9643 erlang:system_info(Item :: info) -> binary()
9644
9645 erlang:system_info(Item :: kernel_poll) -> boolean()
9646
9647 erlang:system_info(Item :: loaded) -> binary()
9648
9649 erlang:system_info(Item :: machine) -> string()
9650
9651 erlang:system_info(Item :: modified_timing_level) ->
9652 integer() | undefined
9653
9654 erlang:system_info(Item :: nif_version) -> string()
9655
9656 erlang:system_info(Item :: otp_release) -> string()
9657
9658 erlang:system_info(Item :: port_parallelism) -> boolean()
9659
9660 erlang:system_info(Item :: system_architecture) -> string()
9661
9662 erlang:system_info(Item :: system_logger) ->
9663 logger | undefined | pid()
9664
9665 erlang:system_info(Item :: system_version) -> string()
9666
9667 erlang:system_info(Item :: trace_control_word) ->
9668 integer() >= 0
9669
9670 erlang:system_info(Item :: version) -> string()
9671
9672 erlang:system_info(Item ::
9673 wordsize |
9674 {wordsize, internal} |
9675 {wordsize, external}) ->
9676 4 | 8
9677
9678 Returns various information about the current system (emulator)
9679 as specified by Item:
9680
9681 build_type:
9682 Deprecated, use emu_type instead
9683
9684 c_compiler_used:
9685 Returns a two-tuple describing the C compiler used when com‐
9686 piling the runtime system. The first element is an atom de‐
9687 scribing the name of the compiler, or undefined if unknown.
9688 The second element is a term describing the version of the
9689 compiler, or undefined if unknown.
9690
9691 check_io:
9692 Returns a list containing miscellaneous information about
9693 the emulators internal I/O checking. Notice that the content
9694 of the returned list can vary between platforms and over
9695 time. It is only guaranteed that a list is returned.
9696
9697 compat_rel:
9698 Returns the compatibility mode of the local node as an inte‐
9699 ger. The integer returned represents the Erlang/OTP release
9700 that the current emulator has been set to be backward com‐
9701 patible with. The compatibility mode can be configured at
9702 startup by using command-line flag +R in erl(1).
9703
9704 debug_compiled:
9705 Returns true if the emulator has been debug-compiled, other‐
9706 wise false.
9707
9708 driver_version:
9709 Returns a string containing the Erlang driver version used
9710 by the runtime system. It has the form "<major ver>.<minor
9711 ver>".
9712
9713 dynamic_trace:
9714 Returns an atom describing the dynamic trace framework com‐
9715 piled into the virtual machine. It can be dtrace, systemtap,
9716 or none. For a commercial or standard build, it is always
9717 none. The other return values indicate a custom configura‐
9718 tion (for example, ./configure --with-dynamic-trace=dtrace).
9719 For more information about dynamic tracing, see dyntrace(3)
9720 manual page and the README.dtrace/README.systemtap files in
9721 the Erlang source code top directory.
9722
9723 dynamic_trace_probes:
9724 Returns a boolean() indicating if dynamic trace probes
9725 (dtrace or systemtap) are built into the emulator. This can
9726 only be true if the virtual machine was built for dynamic
9727 tracing (that is, system_info(dynamic_trace) returns dtrace
9728 or systemtap).
9729
9730 emu_flavor:
9731 Returns an atom describing the flavor of the runtime system.
9732 This will be either emu or jit. Possible return values can
9733 be added or removed at any time without prior notice.
9734
9735 emu_type:
9736 Returns an atom describing the build type of the runtime
9737 system. This is normally the atom opt for optimized. Other
9738 possible return values are debug, gcov, valgrind, gprof, and
9739 lcnt. Possible return values can be added or removed at any
9740 time without prior notice.
9741
9742 info:
9743 Returns a binary containing a string of miscellaneous system
9744 information formatted as in Erlang crash dumps. For more in‐
9745 formation, see section How to interpret the Erlang crash
9746 dumps in the User's Guide.
9747
9748 kernel_poll:
9749 Returns true if the emulator uses some kind of kernel-poll
9750 implementation, otherwise false.
9751
9752 loaded:
9753 Returns a binary containing a string of loaded module infor‐
9754 mation formatted as in Erlang crash dumps. For more informa‐
9755 tion, see section How to interpret the Erlang crash dumps in
9756 the User's Guide.
9757
9758 machine:
9759 Returns a string containing the Erlang machine name.
9760
9761 modified_timing_level:
9762 Returns the modified timing-level (an integer) if modified
9763 timing is enabled, otherwise undefined. For more information
9764 about modified timing, see command-line flag +T in erl(1)
9765
9766 nif_version:
9767 Returns a string containing the version of the Erlang NIF
9768 interface used by the runtime system. It is on the form
9769 "<major ver>.<minor ver>".
9770
9771 otp_release:
9772
9773
9774 Returns a string containing the OTP release number of the
9775 OTP release that the currently executing ERTS application is
9776 part of.
9777
9778 As from Erlang/OTP 17, the OTP release number corresponds to
9779 the major OTP version number. No erlang:system_info() argu‐
9780 ment gives the exact OTP version. This is because the exact
9781 OTP version in the general case is difficult to determine.
9782 For more information, see the description of versions in
9783 System principles in System Documentation.
9784
9785 port_parallelism:
9786 Returns the default port parallelism scheduling hint used.
9787 For more information, see command-line argument +spp in
9788 erl(1).
9789
9790 system_architecture:
9791 Returns a string containing the processor and OS architec‐
9792 ture the emulator is built for.
9793
9794 system_logger:
9795 Returns the current system_logger as set by erlang:sys‐
9796 tem_flag(system_logger, _).
9797
9798 system_version:
9799 Returns a string containing version number and some impor‐
9800 tant properties, such as the number of schedulers.
9801
9802 trace_control_word:
9803 Returns the value of the node trace control word. For more
9804 information, see function get_tcw in section Match Specifi‐
9805 cations in Erlang in the User's Guide.
9806
9807 version:
9808 Returns a string containing the version number of the emula‐
9809 tor.
9810
9811 wordsize:
9812 Same as {wordsize, internal}.
9813
9814 {wordsize, internal}:
9815 Returns the size of Erlang term words in bytes as an inte‐
9816 ger, that is, 4 is returned on a 32-bit architecture, and 8
9817 is returned on a 64-bit architecture.
9818
9819 {wordsize, external}:
9820 Returns the true word size of the emulator, that is, the
9821 size of a pointer. The value is given in bytes as an inte‐
9822 ger. On a pure 32-bit architecture, 4 is returned. On a
9823 64-bit architecture, 8 is returned.
9824
9825 erlang:system_monitor() -> MonSettings
9826
9827 Types:
9828
9829 MonSettings = undefined | {MonitorPid, Options}
9830 MonitorPid = pid()
9831 Options = [system_monitor_option()]
9832 system_monitor_option() =
9833 busy_port | busy_dist_port |
9834 {long_gc, integer() >= 0} |
9835 {long_schedule, integer() >= 0} |
9836 {large_heap, integer() >= 0}
9837
9838 Returns the current system monitoring settings set by er‐
9839 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
9840 no settings exist. The order of the options can be different
9841 from the one that was set.
9842
9843 erlang:system_monitor(Arg) -> MonSettings
9844
9845 Types:
9846
9847 Arg = MonSettings = undefined | {MonitorPid, Options}
9848 MonitorPid = pid()
9849 Options = [system_monitor_option()]
9850 system_monitor_option() =
9851 busy_port | busy_dist_port |
9852 {long_gc, integer() >= 0} |
9853 {long_schedule, integer() >= 0} |
9854 {large_heap, integer() >= 0}
9855
9856 When called with argument undefined, all system performance mon‐
9857 itoring settings are cleared.
9858
9859 Calling the function with {MonitorPid, Options} as argument is
9860 the same as calling erlang:system_monitor(MonitorPid, Options).
9861
9862 Returns the previous system monitor settings just like er‐
9863 lang:system_monitor/0.
9864
9865 erlang:system_monitor(MonitorPid, Options) -> MonSettings
9866
9867 Types:
9868
9869 MonitorPid = pid()
9870 Options = [system_monitor_option()]
9871 MonSettings = undefined | {OldMonitorPid, OldOptions}
9872 OldMonitorPid = pid()
9873 OldOptions = [system_monitor_option()]
9874 system_monitor_option() =
9875 busy_port | busy_dist_port |
9876 {long_gc, integer() >= 0} |
9877 {long_schedule, integer() >= 0} |
9878 {large_heap, integer() >= 0}
9879
9880 Sets the system performance monitoring options. MonitorPid is a
9881 local process identifier (pid) receiving system monitor mes‐
9882 sages. The second argument is a list of monitoring options:
9883
9884 {long_gc, Time}:
9885 If a garbage collection in the system takes at least Time
9886 wall clock milliseconds, a message {monitor, GcPid, long_gc,
9887 Info} is sent to MonitorPid. GcPid is the pid that was
9888 garbage collected. Info is a list of two-element tuples de‐
9889 scribing the result of the garbage collection.
9890
9891 One of the tuples is {timeout, GcTime}, where GcTime is the
9892 time for the garbage collection in milliseconds. The other
9893 tuples are tagged with heap_size, heap_block_size,
9894 stack_size, mbuf_size, old_heap_size, and
9895 old_heap_block_size. These tuples are explained in the de‐
9896 scription of trace message gc_minor_start (see er‐
9897 lang:trace/3). New tuples can be added, and the order of the
9898 tuples in the Info list can be changed at any time without
9899 prior notice.
9900
9901 {long_schedule, Time}:
9902 If a process or port in the system runs uninterrupted for at
9903 least Time wall clock milliseconds, a message {monitor, Pi‐
9904 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
9905 Port is the process or port that was running. Info is a list
9906 of two-element tuples describing the event.
9907
9908 If a pid(), the tuples {timeout, Millis}, {in, Location},
9909 and {out, Location} are present, where Location is either an
9910 MFA ({Module, Function, Arity}) describing the function
9911 where the process was scheduled in/out, or the atom unde‐
9912 fined.
9913
9914 If a port(), the tuples {timeout, Millis} and {port_op,Op}
9915 are present. Op is one of proc_sig, timeout, input, output,
9916 event, or dist_cmd, depending on which driver callback was
9917 executing.
9918
9919 proc_sig is an internal operation and is never to appear,
9920 while the others represent the corresponding driver call‐
9921 backs timeout, ready_input, ready_output, event, and outputv
9922 (when the port is used by distribution). Value Millis in tu‐
9923 ple timeout informs about the uninterrupted execution time
9924 of the process or port, which always is equal to or higher
9925 than the Time value supplied when starting the trace. New
9926 tuples can be added to the Info list in a future release.
9927 The order of the tuples in the list can be changed at any
9928 time without prior notice.
9929
9930 This can be used to detect problems with NIFs or drivers
9931 that take too long to execute. 1 ms is considered a good
9932 maximum time for a driver callback or a NIF. However, a
9933 time-sharing system is usually to consider everything < 100
9934 ms as "possible" and fairly "normal". However, longer sched‐
9935 ule times can indicate swapping or a misbehaving NIF/driver.
9936 Misbehaving NIFs and drivers can cause bad resource utiliza‐
9937 tion and bad overall system performance.
9938
9939 {large_heap, Size}:
9940 If a garbage collection in the system results in the allo‐
9941 cated size of a heap being at least Size words, a message
9942 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
9943 GcPid and Info are the same as for long_gc earlier, except
9944 that the tuple tagged with timeout is not present.
9945
9946 The monitor message is sent if the sum of the sizes of all
9947 memory blocks allocated for all heap generations after a
9948 garbage collection is equal to or higher than Size.
9949
9950 When a process is killed by max_heap_size, it is killed be‐
9951 fore the garbage collection is complete and thus no large
9952 heap message is sent.
9953
9954 busy_port:
9955 If a process in the system gets suspended because it sends
9956 to a busy port, a message {monitor, SusPid, busy_port, Port}
9957 is sent to MonitorPid. SusPid is the pid that got suspended
9958 when sending to Port.
9959
9960 busy_dist_port:
9961 If a process in the system gets suspended because it sends
9962 to a process on a remote node whose inter-node communication
9963 was handled by a busy port, a message {monitor, SusPid,
9964 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
9965 pid that got suspended when sending through the inter-node
9966 communication port Port.
9967
9968 Returns the previous system monitor settings just like er‐
9969 lang:system_monitor/0.
9970
9971 The arguments to system_monitor/2 specifies how all system moni‐
9972 toring on the node should be done, not how it should be changed.
9973 This means only one process at a time (MonitorPid) can be the
9974 receiver of system monitor messages. Also, the way to clear a
9975 specific monitor option is to not include it in the list Op‐
9976 tions. All system monitoring will, however, be cleared if the
9977 process identified by MonitorPid terminates.
9978
9979 There are no special option values (like zero) to clear an op‐
9980 tion. Some of the options have a unspecified minimum value.
9981 Lower values will be adjusted to the minimum value. For example,
9982 it is currently not possible to monitor all garbage collections
9983 with {long_gc, 0}.
9984
9985 Note:
9986 If a monitoring process gets so large that it itself starts to
9987 cause system monitor messages when garbage collecting, the mes‐
9988 sages enlarge the process message queue and probably make the
9989 problem worse.
9990
9991 Keep the monitoring process neat and do not set the system moni‐
9992 tor limits too tight.
9993
9994
9995 Failures:
9996
9997 badarg:
9998 If MonitorPid does not exist.
9999
10000 badarg:
10001 If MonitorPid is not a local process.
10002
10003 erlang:system_profile() -> ProfilerSettings
10004
10005 Types:
10006
10007 ProfilerSettings = undefined | {ProfilerPid, Options}
10008 ProfilerPid = pid() | port()
10009 Options = [system_profile_option()]
10010 system_profile_option() =
10011 exclusive | runnable_ports | runnable_procs | scheduler |
10012 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10013
10014 Returns the current system profiling settings set by erlang:sys‐
10015 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
10016 are no settings. The order of the options can be different from
10017 the one that was set.
10018
10019 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
10020
10021 Types:
10022
10023 ProfilerPid = pid() | port() | undefined
10024 Options = [system_profile_option()]
10025 ProfilerSettings =
10026 undefined | {pid() | port(), [system_profile_option()]}
10027 system_profile_option() =
10028 exclusive | runnable_ports | runnable_procs | scheduler |
10029 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10030
10031 Sets system profiler options. ProfilerPid is a local process
10032 identifier (pid) or port receiving profiling messages. The re‐
10033 ceiver is excluded from all profiling. The second argument is a
10034 list of profiling options:
10035
10036 exclusive:
10037 If a synchronous call to a port from a process is done, the
10038 calling process is considered not runnable during the call
10039 runtime to the port. The calling process is notified as in‐
10040 active, and later active when the port callback returns.
10041
10042 monotonic_timestamp:
10043 Time stamps in profile messages use Erlang monotonic time.
10044 The time stamp (Ts) has the same format and value as pro‐
10045 duced by erlang:monotonic_time(nanosecond).
10046
10047 runnable_procs:
10048 If a process is put into or removed from the run queue, a
10049 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
10050 erPid. Running processes that are reinserted into the run
10051 queue after having been pre-empted do not trigger this mes‐
10052 sage.
10053
10054 runnable_ports:
10055 If a port is put into or removed from the run queue, a mes‐
10056 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
10057
10058 scheduler:
10059 If a scheduler is put to sleep or awoken, a message, {pro‐
10060 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
10061 filerPid.
10062
10063 strict_monotonic_timestamp:
10064 Time stamps in profile messages consist of Erlang monotonic
10065 time and a monotonically increasing integer. The time stamp
10066 (Ts) has the same format and value as produced by {er‐
10067 lang:monotonic_time(nanosecond), erlang:unique_inte‐
10068 ger([monotonic])}.
10069
10070 timestamp:
10071 Time stamps in profile messages include a time stamp (Ts)
10072 that has the same form as returned by erlang:now(). This is
10073 also the default if no time stamp flag is specified. If
10074 cpu_timestamp has been enabled through erlang:trace/3, this
10075 also effects the time stamp produced in profiling messages
10076 when flag timestamp is enabled.
10077
10078 Note:
10079 erlang:system_profile behavior can change in a future release.
10080
10081
10082 erlang:system_time() -> integer()
10083
10084 Returns current Erlang system time in native time unit.
10085
10086 Calling erlang:system_time() is equivalent to erlang:mono‐
10087 tonic_time() + erlang:time_offset().
10088
10089 Note:
10090 This time is not a monotonically increasing time in the general
10091 case. For more information, see the documentation of time warp
10092 modes in the User's Guide.
10093
10094
10095 erlang:system_time(Unit) -> integer()
10096
10097 Types:
10098
10099 Unit = time_unit()
10100
10101 Returns current Erlang system time converted into the Unit
10102 passed as argument.
10103
10104 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
10105 vert_time_unit(erlang:system_time(), native, Unit).
10106
10107 Note:
10108 This time is not a monotonically increasing time in the general
10109 case. For more information, see the documentation of time warp
10110 modes in the User's Guide.
10111
10112
10113 term_to_binary(Term) -> ext_binary()
10114
10115 Types:
10116
10117 Term = term()
10118
10119 Returns a binary data object that is the result of encoding Term
10120 according to the Erlang external term format.
10121
10122 This can be used for various purposes, for example, writing a
10123 term to a file in an efficient way, or sending an Erlang term to
10124 some type of communications channel not supported by distributed
10125 Erlang.
10126
10127 > Bin = term_to_binary(hello).
10128 <<131,100,0,5,104,101,108,108,111>>
10129 > hello = binary_to_term(Bin).
10130 hello
10131
10132
10133 See also binary_to_term/1.
10134
10135 Note:
10136 There is no guarantee that this function will return the same
10137 encoded representation for the same term.
10138
10139
10140 term_to_binary(Term, Options) -> ext_binary()
10141
10142 Types:
10143
10144 Term = term()
10145 Options =
10146 [compressed |
10147 {compressed, Level :: 0..9} |
10148 deterministic |
10149 {minor_version, Version :: 0..2}]
10150
10151 Returns a binary data object that is the result of encoding Term
10152 according to the Erlang external term format.
10153
10154 If option compressed is provided, the external term format is
10155 compressed. The compressed format is automatically recognized by
10156 binary_to_term/1 as from Erlang/OTP R7B.
10157
10158 A compression level can be specified by giving option {com‐
10159 pressed, Level}. Level is an integer with range 0..9, where:
10160
10161 * 0 - No compression is done (it is the same as giving no com‐
10162 pressed option).
10163
10164 * 1 - Takes least time but may not compress as well as the
10165 higher levels.
10166
10167 * 6 - Default level when option compressed is provided.
10168
10169 * 9 - Takes most time and tries to produce a smaller result.
10170 Notice "tries" in the preceding sentence; depending on the
10171 input term, level 9 compression either does or does not pro‐
10172 duce a smaller result than level 1 compression.
10173
10174 Option {minor_version, Version} can be used to control some en‐
10175 coding details. This option was introduced in Erlang/OTP R11B-4.
10176 The valid values for Version are:
10177
10178 0:
10179 Floats are encoded using a textual representation. This op‐
10180 tion is useful to ensure that releases before Erlang/OTP
10181 R11B-4 can decode resulting binary.
10182
10183 This version encode atoms that can be represented by a
10184 latin1 string using latin1 encoding while only atoms that
10185 cannot be represented by latin1 are encoded using utf8.
10186
10187 1:
10188 This is as of Erlang/OTP 17.0 the default. It forces any
10189 floats in the term to be encoded in a more space-efficient
10190 and exact way (namely in the 64-bit IEEE format, rather than
10191 converted to a textual representation). As from Erlang/OTP
10192 R11B-4, binary_to_term/1 can decode this representation.
10193
10194 This version encode atoms that can be represented by a
10195 latin1 string using latin1 encoding while only atoms that
10196 cannot be represented by latin1 are encoded using utf8.
10197
10198 2:
10199 Drops usage of the latin1 atom encoding and unconditionally
10200 use utf8 encoding for all atoms. This will be changed to the
10201 default in a future major release of Erlang/OTP. Erlang/OTP
10202 systems as of R16B can decode this representation.
10203
10204 Option deterministic (introduced in OTP 24.1) can be used to en‐
10205 sure that within the same major release of Erlang/OTP, the same
10206 encoded representation is returned for the same term. There is
10207 still no guarantee that the encoded representation remains the
10208 same between major releases of Erlang/OTP.
10209
10210 See also binary_to_term/1.
10211
10212 term_to_iovec(Term) -> ext_iovec()
10213
10214 Types:
10215
10216 Term = term()
10217
10218 Returns the encoding of Term according to the Erlang external
10219 term format as ext_iovec().
10220
10221 This function produce the same encoding as term_to_binary/1, but
10222 with another return type. The call iolist_to_bi‐
10223 nary(term_to_iovec(Term)) will produce exactly the same result
10224 as the call term_to_binary(Term).
10225
10226 term_to_iovec() is a pure optimization of the functionality
10227 term_to_binary() provide. term_to_iovec() can for example refer
10228 directly to off heap binaries instead of copying the binary data
10229 into the result.
10230
10231 See also term_to_binary/1.
10232
10233 term_to_iovec(Term, Options) -> ext_iovec()
10234
10235 Types:
10236
10237 Term = term()
10238 Options =
10239 [compressed |
10240 {compressed, Level :: 0..9} |
10241 deterministic |
10242 {minor_version, Version :: 0..2}]
10243
10244 Returns the encoding of Term according to the Erlang external
10245 term format as ext_iovec().
10246
10247 This function produce the same encoding as term_to_binary/2, but
10248 with another return type. The call iolist_to_bi‐
10249 nary(term_to_iovec(Term, Opts)) will produce exactly the same
10250 result as term_to_binary(Term, Opts).
10251
10252 Currently recognised options are all options recognised by
10253 term_to_binary/2.
10254
10255 term_to_iovec() is a pure optimization of the functionality
10256 term_to_binary() provide. term_to_iovec() can for example refer
10257 directly to off heap binaries instead of copying the binary data
10258 into the result.
10259
10260 See also term_to_binary/2.
10261
10262 throw(Any) -> no_return()
10263
10264 Types:
10265
10266 Any = term()
10267
10268 Raises an exception of class throw. Intended to be used to do
10269 non-local returns from functions.
10270
10271 If evaluated within a catch expression, the catch expression
10272 returns value Any. Example:
10273
10274 > catch throw({hello, there}).
10275 {hello,there}
10276
10277 If evaluated within a try-block of a try expression, the value
10278 Any can be caught within the catch block. Example:
10279
10280 try
10281 throw({my_exception, "Something happened"})
10282 catch
10283 throw:{my_exception, Desc} ->
10284 io:format(standard_error, "Error: ~s~n", [Desc])
10285 end
10286
10287 Failure: nocatch if not caught by an exception handler.
10288
10289 See the guide about errors and error handling for additional in‐
10290 formation.
10291
10292 time() -> Time
10293
10294 Types:
10295
10296 Time = calendar:time()
10297
10298 Returns the current time as {Hour, Minute, Second}.
10299
10300 The time zone and Daylight Saving Time correction depend on the
10301 underlying OS. The return value is based on the OS System Time.
10302 Example:
10303
10304 > time().
10305 {9,42,44}
10306
10307 erlang:time_offset() -> integer()
10308
10309 Returns the current time offset between Erlang monotonic time
10310 and Erlang system time in native time unit. Current time offset
10311 added to an Erlang monotonic time gives corresponding Erlang
10312 system time.
10313
10314 The time offset may or may not change during operation depending
10315 on the time warp mode used.
10316
10317 Note:
10318 A change in time offset can be observed at slightly different
10319 points in time by different processes.
10320
10321 If the runtime system is in multi-time warp mode, the time off‐
10322 set is changed when the runtime system detects that the OS sys‐
10323 tem time has changed. The runtime system will, however, not de‐
10324 tect this immediately when it occurs. A task checking the time
10325 offset is scheduled to execute at least once a minute; so, under
10326 normal operation this is to be detected within a minute, but
10327 during heavy load it can take longer time.
10328
10329
10330 erlang:time_offset(Unit) -> integer()
10331
10332 Types:
10333
10334 Unit = time_unit()
10335
10336 Returns the current time offset between Erlang monotonic time
10337 and Erlang system time converted into the Unit passed as argu‐
10338 ment.
10339
10340 Same as calling erlang:convert_time_unit(erlang:time_offset(),
10341 native, Unit) however optimized for commonly used Units.
10342
10343 erlang:timestamp() -> Timestamp
10344
10345 Types:
10346
10347 Timestamp = timestamp()
10348 timestamp() =
10349 {MegaSecs :: integer() >= 0,
10350 Secs :: integer() >= 0,
10351 MicroSecs :: integer() >= 0}
10352
10353 Returns current Erlang system time on the format {MegaSecs,
10354 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
10355 the deprecated erlang:now/0 use. The reason for the existence of
10356 erlang:timestamp() is purely to simplify use for existing code
10357 that assumes this time stamp format. Current Erlang system time
10358 can more efficiently be retrieved in the time unit of your
10359 choice using erlang:system_time/1.
10360
10361 The erlang:timestamp() BIF is equivalent to:
10362
10363 timestamp() ->
10364 ErlangSystemTime = erlang:system_time(microsecond),
10365 MegaSecs = ErlangSystemTime div 1000_000_000_000,
10366 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
10367 MicroSecs = ErlangSystemTime rem 1000_000,
10368 {MegaSecs, Secs, MicroSecs}.
10369
10370 It, however, uses a native implementation that does not build
10371 garbage on the heap and with slightly better performance.
10372
10373 Note:
10374 This time is not a monotonically increasing time in the general
10375 case. For more information, see the documentation of time warp
10376 modes in the User's Guide.
10377
10378
10379 tl(List) -> term()
10380
10381 Types:
10382
10383 List = nonempty_maybe_improper_list()
10384
10385 Returns the tail of List, that is, the list minus the first ele‐
10386 ment, for example:
10387
10388 > tl([geesties, guilies, beasties]).
10389 [guilies, beasties]
10390
10391 > tl([geesties]).
10392 []
10393
10394 > tl([geesties, guilies, beasties | improper_end]).
10395 [guilies, beasties | improper_end]
10396
10397 > tl([geesties | improper_end]).
10398 improper_end
10399
10400 Allowed in guard tests.
10401
10402 Failure: badarg if List is the empty list [].
10403
10404 erlang:trace(PidPortSpec, How, FlagList) -> integer()
10405
10406 Types:
10407
10408 PidPortSpec =
10409 pid() |
10410 port() |
10411 all | processes | ports | existing | existing_processes |
10412 existing_ports | new | new_processes | new_ports
10413 How = boolean()
10414 FlagList = [trace_flag()]
10415 trace_flag() =
10416 all | send | 'receive' | procs | ports | call | arity |
10417 return_to | silent | running | exiting | running_procs |
10418 running_ports | garbage_collection | timestamp |
10419 cpu_timestamp | monotonic_timestamp |
10420 strict_monotonic_timestamp | set_on_spawn |
10421 set_on_first_spawn | set_on_link | set_on_first_link |
10422 {tracer, pid() | port()} |
10423 {tracer, module(), term()}
10424
10425 Turns on (if How == true) or off (if How == false) the trace
10426 flags in FlagList for the process or processes represented by
10427 PidPortSpec.
10428
10429 PidPortSpec is either a process identifier (pid) for a local
10430 process, a port identifier, or one of the following atoms:
10431
10432 all:
10433 All currently existing processes and ports and all that will
10434 be created in the future.
10435
10436 processes:
10437 All currently existing processes and all that will be cre‐
10438 ated in the future.
10439
10440 ports:
10441 All currently existing ports and all that will be created in
10442 the future.
10443
10444 existing:
10445 All currently existing processes and ports.
10446
10447 existing_processes:
10448 All currently existing processes.
10449
10450 existing_ports:
10451 All currently existing ports.
10452
10453 new:
10454 All processes and ports that will be created in the future.
10455
10456 new_processes:
10457 All processes that will be created in the future.
10458
10459 new_ports:
10460 All ports that will be created in the future.
10461
10462 FlagList can contain any number of the following flags (the
10463 "message tags" refers to the list of trace messages):
10464
10465 all:
10466 Sets all trace flags except tracer and cpu_timestamp, which
10467 are in their nature different than the others.
10468
10469 send:
10470 Traces sending of messages.
10471
10472 Message tags: send and send_to_non_existing_process.
10473
10474 'receive':
10475 Traces receiving of messages.
10476
10477 Message tags: 'receive'.
10478
10479 call:
10480 Traces certain function calls. Specify which function calls
10481 to trace by calling erlang:trace_pattern/3.
10482
10483 Message tags: call and return_from.
10484
10485 silent:
10486 Used with the call trace flag. The call, return_from, and
10487 return_to trace messages are inhibited if this flag is set,
10488 but they are executed as normal if there are match specifi‐
10489 cations.
10490
10491 Silent mode is inhibited by executing erlang:trace(_, false,
10492 [silent|_]), or by a match specification executing the func‐
10493 tion {silent, false}.
10494
10495 The silent trace flag facilitates setting up a trace on many
10496 or even all processes in the system. The trace can then be
10497 activated and deactivated using the match specification
10498 function {silent,Bool}, giving a high degree of control of
10499 which functions with which arguments that trigger the trace.
10500
10501 Message tags: call, return_from, and return_to. Or rather,
10502 the absence of.
10503
10504 return_to:
10505 Used with the call trace flag. Traces the return from a
10506 traced function back to its caller. Only works for functions
10507 traced with option local to erlang:trace_pattern/3.
10508
10509 The semantics is that a trace message is sent when a call
10510 traced function returns, that is, when a chain of tail re‐
10511 cursive calls ends. Only one trace message is sent per chain
10512 of tail recursive calls, so the properties of tail recur‐
10513 siveness for function calls are kept while tracing with this
10514 flag. Using call and return_to trace together makes it pos‐
10515 sible to know exactly in which function a process executes
10516 at any time.
10517
10518 To get trace messages containing return values from func‐
10519 tions, use the {return_trace} match specification action in‐
10520 stead.
10521
10522 Message tags: return_to.
10523
10524 procs:
10525 Traces process-related events.
10526
10527 Message tags: spawn, spawned, exit, register, unregister,
10528 link, unlink, getting_linked, and getting_unlinked.
10529
10530 ports:
10531 Traces port-related events.
10532
10533 Message tags: open, closed, register, unregister, get‐
10534 ting_linked, and getting_unlinked.
10535
10536 running:
10537 Traces scheduling of processes.
10538
10539 Message tags: in and out.
10540
10541 exiting:
10542 Traces scheduling of exiting processes.
10543
10544 Message tags: in_exiting, out_exiting, and out_exited.
10545
10546 running_procs:
10547 Traces scheduling of processes just like running. However,
10548 this option also includes schedule events when the process
10549 executes within the context of a port without being sched‐
10550 uled out itself.
10551
10552 Message tags: in and out.
10553
10554 running_ports:
10555 Traces scheduling of ports.
10556
10557 Message tags: in and out.
10558
10559 garbage_collection:
10560 Traces garbage collections of processes.
10561
10562 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
10563 nor_end.
10564
10565 timestamp:
10566 Includes a time stamp in all trace messages. The time stamp
10567 (Ts) has the same form as returned by erlang:now().
10568
10569 cpu_timestamp:
10570 A global trace flag for the Erlang node that makes all trace
10571 time stamps using flag timestamp to be in CPU time, not wall
10572 clock time. That is, cpu_timestamp is not be used if mono‐
10573 tonic_timestamp or strict_monotonic_timestamp is enabled.
10574 Only allowed with PidPortSpec==all. If the host machine OS
10575 does not support high-resolution CPU time measurements,
10576 trace/3 exits with badarg. Notice that most OS do not syn‐
10577 chronize this value across cores, so be prepared that time
10578 can seem to go backwards when using this option.
10579
10580 monotonic_timestamp:
10581 Includes an Erlang monotonic time time stamp in all trace
10582 messages. The time stamp (Ts) has the same format and value
10583 as produced by erlang:monotonic_time(nanosecond). This flag
10584 overrides flag cpu_timestamp.
10585
10586 strict_monotonic_timestamp:
10587 Includes an time stamp consisting of Erlang monotonic time
10588 and a monotonically increasing integer in all trace mes‐
10589 sages. The time stamp (Ts) has the same format and value as
10590 produced by { erlang:monotonic_time(nanosecond), er‐
10591 lang:unique_integer([monotonic])}. This flag overrides flag
10592 cpu_timestamp.
10593
10594 arity:
10595 Used with the call trace flag. {M, F, Arity} is specified
10596 instead of {M, F, Args} in call trace messages.
10597
10598 set_on_spawn:
10599 Makes any process created by a traced process inherit its
10600 trace flags, including flag set_on_spawn.
10601
10602 set_on_first_spawn:
10603 Makes the first process created by a traced process inherit
10604 its trace flags, excluding flag set_on_first_spawn.
10605
10606 set_on_link:
10607 Makes any process linked by a traced process inherit its
10608 trace flags, including flag set_on_link.
10609
10610 set_on_first_link:
10611 Makes the first process linked to by a traced process in‐
10612 herit its trace flags, excluding flag set_on_first_link.
10613
10614 {tracer, Tracer}:
10615 Specifies where to send the trace messages. Tracer must be
10616 the process identifier of a local process or the port iden‐
10617 tifier of a local port.
10618
10619 {tracer, TracerModule, TracerState}:
10620 Specifies that a tracer module is to be called instead of
10621 sending a trace message. The tracer module can then ignore
10622 or change the trace message. For more details on how to
10623 write a tracer module, see erl_tracer(3).
10624
10625 If no tracer is specified, the calling process receives all the
10626 trace messages.
10627
10628 The effect of combining set_on_first_link with set_on_link is
10629 the same as set_on_first_link alone. Likewise for set_on_spawn
10630 and set_on_first_spawn.
10631
10632 The tracing process receives the trace messages described in the
10633 following list. Pid is the process identifier of the traced
10634 process in which the traced event has occurred. The third tuple
10635 element is the message tag.
10636
10637 If flag timestamp, strict_monotonic_timestamp, or mono‐
10638 tonic_timestamp is specified, the first tuple element is
10639 trace_ts instead, and the time stamp is added as an extra ele‐
10640 ment last in the message tuple. If multiple time stamp flags are
10641 passed, timestamp has precedence over strict_monotonic_time‐
10642 stamp, which in turn has precedence over monotonic_timestamp.
10643 All time stamp flags are remembered, so if two are passed and
10644 the one with highest precedence later is disabled, the other one
10645 becomes active.
10646
10647 If a match specification (applicable only for call, send and
10648 'receive' tracing) contains a {message} action function with a
10649 non-boolean value, that value is added as an extra element to
10650 the message tuple either in the last position or before the
10651 timestamp (if it is present).
10652
10653 Trace messages:
10654
10655 {trace, PidPort, send, Msg, To}:
10656 When PidPort sends message Msg to process To.
10657
10658 {trace, PidPort, send_to_non_existing_process, Msg, To}:
10659 When PidPort sends message Msg to the non-existing process
10660 To.
10661
10662 {trace, PidPort, 'receive', Msg}:
10663 When PidPort receives message Msg. If Msg is set to time-
10664 out, a receive statement can have timed out, or the process
10665 received a message with the payload timeout.
10666
10667 {trace, Pid, call, {M, F, Args}}:
10668 When Pid calls a traced function. The return values of calls
10669 are never supplied, only the call and its arguments.
10670
10671 Trace flag arity can be used to change the contents of this
10672 message, so that Arity is specified instead of Args.
10673
10674 {trace, Pid, return_to, {M, F, Arity}}:
10675 When Pid returns to the specified function. This trace mes‐
10676 sage is sent if both the flags call and return_to are set,
10677 and the function is set to be traced on local function
10678 calls. The message is only sent when returning from a chain
10679 of tail recursive function calls, where at least one call
10680 generated a call trace message (that is, the functions match
10681 specification matched, and {message, false} was not an ac‐
10682 tion).
10683
10684 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
10685 When Pid returns from the specified function. This trace
10686 message is sent if flag call is set, and the function has a
10687 match specification with a return_trace or exception_trace
10688 action.
10689
10690 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
10691 When Pid exits from the specified function because of an ex‐
10692 ception. This trace message is sent if flag call is set, and
10693 the function has a match specification with an excep‐
10694 tion_trace action.
10695
10696 {trace, Pid, spawn, Pid2, {M, F, Args}}:
10697 When Pid spawns a new process Pid2 with the specified func‐
10698 tion call as entry point.
10699
10700 Args is supposed to be the argument list, but can be any
10701 term if the spawn is erroneous.
10702
10703 {trace, Pid, spawned, Pid2, {M, F, Args}}:
10704 When Pid is spawned by process Pid2 with the specified func‐
10705 tion call as entry point.
10706
10707 Args is supposed to be the argument list, but can be any
10708 term if the spawn is erroneous.
10709
10710 {trace, Pid, exit, Reason}:
10711 When Pid exits with reason Reason.
10712
10713 {trace, PidPort, register, RegName}:
10714 When PidPort gets the name RegName registered.
10715
10716 {trace, PidPort, unregister, RegName}:
10717 When PidPort gets the name RegName unregistered. This is
10718 done automatically when a registered process or port exits.
10719
10720 {trace, Pid, link, Pid2}:
10721 When Pid links to a process Pid2.
10722
10723 {trace, Pid, unlink, Pid2}:
10724 When Pid removes the link from a process Pid2.
10725
10726 {trace, PidPort, getting_linked, Pid2}:
10727 When PidPort gets linked to a process Pid2.
10728
10729 {trace, PidPort, getting_unlinked, Pid2}:
10730 When PidPort gets unlinked from a process Pid2.
10731
10732 {trace, Port, open, Pid, Driver}:
10733 When Pid opens a new port Port with the running Driver.
10734
10735 Driver is the name of the driver as an atom.
10736
10737 {trace, Port, closed, Reason}:
10738 When Port closes with Reason.
10739
10740 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
10741 When Pid is scheduled to run. The process runs in function
10742 {M, F, Arity}. On some rare occasions, the current function
10743 cannot be determined, then the last element is 0.
10744
10745 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
10746 0}:
10747 When Pid is scheduled out. The process was running in func‐
10748 tion {M, F, Arity}. On some rare occasions, the current
10749 function cannot be determined, then the last element is 0.
10750
10751 {trace, Port, in, Command | 0}:
10752 When Port is scheduled to run. Command is the first thing
10753 the port will execute, it can however run several commands
10754 before being scheduled out. On some rare occasions, the cur‐
10755 rent function cannot be determined, then the last element is
10756 0.
10757
10758 The possible commands are call, close, command, connect,
10759 control, flush, info, link, open, and unlink.
10760
10761 {trace, Port, out, Command | 0}:
10762 When Port is scheduled out. The last command run was Com‐
10763 mand. On some rare occasions, the current function cannot be
10764 determined, then the last element is 0. Command can contain
10765 the same commands as in
10766
10767 {trace, Pid, gc_minor_start, Info}:
10768
10769
10770 Sent when a young garbage collection is about to be started.
10771 Info is a list of two-element tuples, where the first ele‐
10772 ment is a key, and the second is the value. Do not depend on
10773 any order of the tuples. The following keys are defined:
10774
10775 heap_size:
10776 The size of the used part of the heap.
10777
10778 heap_block_size:
10779 The size of the memory block used for storing the heap and
10780 the stack.
10781
10782 old_heap_size:
10783 The size of the used part of the old heap.
10784
10785 old_heap_block_size:
10786 The size of the memory block used for storing the old
10787 heap.
10788
10789 stack_size:
10790 The size of the stack.
10791
10792 recent_size:
10793 The size of the data that survived the previous garbage
10794 collection.
10795
10796 mbuf_size:
10797 The combined size of message buffers associated with the
10798 process.
10799
10800 bin_vheap_size:
10801 The total size of unique off-heap binaries referenced from
10802 the process heap.
10803
10804 bin_vheap_block_size:
10805 The total size of binaries allowed in the virtual heap in
10806 the process before doing a garbage collection.
10807
10808 bin_old_vheap_size:
10809 The total size of unique off-heap binaries referenced from
10810 the process old heap.
10811
10812 bin_old_vheap_block_size:
10813 The total size of binaries allowed in the virtual old heap
10814 in the process before doing a garbage collection.
10815
10816 wordsize:
10817 For the gc_minor_start event it is the size of the need
10818 that triggered the GC. For the corresponding gc_minor_end
10819 event it is the size of reclaimed memory = start heap_size
10820 - end heap_size.
10821
10822 All sizes are in words.
10823
10824 {trace, Pid, gc_max_heap_size, Info}:
10825 Sent when the max_heap_size is reached during garbage col‐
10826 lection. Info contains the same kind of list as in message
10827 gc_start, but the sizes reflect the sizes that triggered
10828 max_heap_size to be reached.
10829
10830 {trace, Pid, gc_minor_end, Info}:
10831 Sent when young garbage collection is finished. Info con‐
10832 tains the same kind of list as in message gc_minor_start,
10833 but the sizes reflect the new sizes after garbage collec‐
10834 tion.
10835
10836 {trace, Pid, gc_major_start, Info}:
10837 Sent when fullsweep garbage collection is about to be
10838 started. Info contains the same kind of list as in message
10839 gc_minor_start.
10840
10841 {trace, Pid, gc_major_end, Info}:
10842 Sent when fullsweep garbage collection is finished. Info
10843 contains the same kind of list as in message gc_minor_start,
10844 but the sizes reflect the new sizes after a fullsweep
10845 garbage collection.
10846
10847 If the tracing process/port dies or the tracer module returns
10848 remove, the flags are silently removed.
10849
10850 Each process can only be traced by one tracer. Therefore, at‐
10851 tempts to trace an already traced process fail.
10852
10853 Returns a number indicating the number of processes that matched
10854 PidPortSpec. If PidPortSpec is a process identifier, the return
10855 value is 1. If PidPortSpec is all or existing, the return value
10856 is the number of processes running. If PidPortSpec is new, the
10857 return value is 0.
10858
10859 Failure: badarg if the specified arguments are not supported.
10860 For example, cpu_timestamp is not supported on all platforms.
10861
10862 erlang:trace_delivered(Tracee) -> Ref
10863
10864 Types:
10865
10866 Tracee = pid() | all
10867 Ref = reference()
10868
10869 The delivery of trace messages (generated by erlang:trace/3,
10870 seq_trace(3), or erlang:system_profile/2) is dislocated on the
10871 time-line compared to other events in the system. If you know
10872 that Tracee has passed some specific point in its execution, and
10873 you want to know when at least all trace messages corresponding
10874 to events up to this point have reached the tracer, use er‐
10875 lang:trace_delivered(Tracee).
10876
10877 When it is guaranteed that all trace messages are delivered to
10878 the tracer up to the point that Tracee reached at the time of
10879 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
10880 ered, Tracee, Ref} message is sent to the caller of er‐
10881 lang:trace_delivered(Tracee) .
10882
10883 Notice that message trace_delivered does not imply that trace
10884 messages have been delivered. Instead it implies that all trace
10885 messages that are to be delivered have been delivered. It is not
10886 an error if Tracee is not, and has not been traced by someone,
10887 but if this is the case, no trace messages have been delivered
10888 when the trace_delivered message arrives.
10889
10890 Notice that Tracee must refer to a process currently or previ‐
10891 ously existing on the same node as the caller of er‐
10892 lang:trace_delivered(Tracee) resides on. The special Tracee atom
10893 all denotes all processes that currently are traced in the node.
10894
10895 When used together with a Tracer Module, any message sent in
10896 the trace callback is guaranteed to have reached its recipient
10897 before the trace_delivered message is sent.
10898
10899 Example: Process A is Tracee, port B is tracer, and process C is
10900 the port owner of B. C wants to close B when A exits. To ensure
10901 that the trace is not truncated, C can call erlang:trace_deliv‐
10902 ered(A) when A exits, and wait for message {trace_delivered, A,
10903 Ref} before closing B.
10904
10905 Failure: badarg if Tracee does not refer to a process (dead or
10906 alive) on the same node as the caller of erlang:trace_deliv‐
10907 ered(Tracee) resides on.
10908
10909 erlang:trace_info(PidPortFuncEvent, Item) -> Res
10910
10911 Types:
10912
10913 PidPortFuncEvent =
10914 pid() |
10915 port() |
10916 new | new_processes | new_ports |
10917 {Module, Function, Arity} |
10918 on_load | send | 'receive'
10919 Module = module()
10920 Function = atom()
10921 Arity = arity()
10922 Item =
10923 flags | tracer | traced | match_spec | meta |
10924 meta_match_spec | call_count | call_time | all
10925 Res = trace_info_return()
10926 trace_info_return() =
10927 undefined |
10928 {flags, [trace_info_flag()]} |
10929 {tracer, pid() | port() | []} |
10930 {tracer, module(), term()} |
10931 trace_info_item_result() |
10932 {all, [trace_info_item_result()] | false | undefined}
10933 trace_info_item_result() =
10934 {traced, global | local | false | undefined} |
10935 {match_spec, trace_match_spec() | false | undefined} |
10936 {meta, pid() | port() | false | undefined | []} |
10937 {meta, module(), term()} |
10938 {meta_match_spec, trace_match_spec() | false | undefined} |
10939 {call_count, integer() >= 0 | boolean() | undefined} |
10940 {call_time,
10941 [{pid(),
10942 integer() >= 0,
10943 integer() >= 0,
10944 integer() >= 0}] |
10945 boolean() |
10946 undefined}
10947 trace_info_flag() =
10948 send | 'receive' | set_on_spawn | call | return_to | procs |
10949 set_on_first_spawn | set_on_link | running |
10950 garbage_collection | timestamp | monotonic_timestamp |
10951 strict_monotonic_timestamp | arity
10952 trace_match_spec() =
10953 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10954 match_variable() = atom()
10955 Approximation of '$1' | '$2' | '$3' | ...
10956
10957 Returns trace information about a port, process, function, or
10958 event.
10959
10960 To get information about a port or process, PidPortFuncEvent is
10961 to be a process identifier (pid), port identifier, or one of the
10962 atoms new, new_processes, or new_ports. The atom new or new_pro‐
10963 cesses means that the default trace state for processes to be
10964 created is returned. The atom new_ports means that the default
10965 trace state for ports to be created is returned.
10966
10967 Valid Items for ports and processes:
10968
10969 flags:
10970 Returns a list of atoms indicating what kind of traces is
10971 enabled for the process. The list is empty if no traces are
10972 enabled, and one or more of the followings atoms if traces
10973 are enabled: send, 'receive', set_on_spawn, call, return_to,
10974 procs, ports, set_on_first_spawn, set_on_link, running, run‐
10975 ning_procs, running_ports, silent, exiting, monotonic_time‐
10976 stamp, strict_monotonic_timestamp, garbage_collection, time‐
10977 stamp, and arity. The order is arbitrary.
10978
10979 tracer:
10980 Returns the identifier for process, port, or a tuple con‐
10981 taining the tracer module and tracer state tracing this
10982 process. If this process is not traced, the return value is
10983 [].
10984
10985 To get information about a function, PidPortFuncEvent is to be
10986 the three-element tuple {Module, Function, Arity} or the atom
10987 on_load. No wildcards are allowed. Returns undefined if the
10988 function does not exist, or false if the function is not traced.
10989 If PidPortFuncEvent is on_load, the information returned refers
10990 to the default value for code that will be loaded.
10991
10992 Valid Items for functions:
10993
10994 traced:
10995 Returns global if this function is traced on global function
10996 calls, local if this function is traced on local function
10997 calls (that is, local and global function calls), and false
10998 if local or global function calls are not traced.
10999
11000 match_spec:
11001 Returns the match specification for this function, if it has
11002 one. If the function is locally or globally traced but has
11003 no match specification defined, the returned value is [].
11004
11005 meta:
11006 Returns the meta-trace tracer process, port, or trace module
11007 for this function, if it has one. If the function is not
11008 meta-traced, the returned value is false. If the function is
11009 meta-traced but has once detected that the tracer process is
11010 invalid, the returned value is [].
11011
11012 meta_match_spec:
11013 Returns the meta-trace match specification for this func‐
11014 tion, if it has one. If the function is meta-traced but has
11015 no match specification defined, the returned value is [].
11016
11017 call_count:
11018 Returns the call count value for this function or true for
11019 the pseudo function on_load if call count tracing is active.
11020 Otherwise false is returned.
11021
11022 See also erlang:trace_pattern/3.
11023
11024 call_time:
11025 Returns the call time values for this function or true for
11026 the pseudo function on_load if call time tracing is active.
11027 Otherwise false is returned. The call time values returned,
11028 [{Pid, Count, S, Us}], is a list of each process that exe‐
11029 cuted the function and its specific counters.
11030
11031 See also erlang:trace_pattern/3.
11032
11033 all:
11034 Returns a list containing the {Item, Value} tuples for all
11035 other items, or returns false if no tracing is active for
11036 this function.
11037
11038 To get information about an event, PidPortFuncEvent is to be one
11039 of the atoms send or 'receive'.
11040
11041 One valid Item for events exists:
11042
11043 match_spec:
11044 Returns the match specification for this event, if it has
11045 one, or true if no match specification has been set.
11046
11047 The return value is {Item, Value}, where Value is the requested
11048 information as described earlier. If a pid for a dead process
11049 was specified, or the name of a non-existing function, Value is
11050 undefined.
11051
11052 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
11053
11054 Types:
11055
11056 MFA = trace_pattern_mfa() | send | 'receive'
11057 MatchSpec =
11058 (MatchSpecList :: trace_match_spec()) |
11059 boolean() |
11060 restart | pause
11061 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11062 trace_match_spec() =
11063 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11064 match_variable() = atom()
11065 Approximation of '$1' | '$2' | '$3' | ...
11066
11067 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
11068 for backward compatibility.
11069
11070 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
11071 integer() >= 0
11072
11073 Types:
11074
11075 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11076 trace_match_spec() =
11077 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11078 match_variable() = atom()
11079 Approximation of '$1' | '$2' | '$3' | ...
11080
11081 Sets trace pattern for message sending. Must be combined with
11082 erlang:trace/3 to set the send trace flag for one or more pro‐
11083 cesses. By default all messages sent from send traced processes
11084 are traced. To limit traced send events based on the message
11085 content, the sender and/or the receiver, use erlang:trace_pat‐
11086 tern/3.
11087
11088 Argument MatchSpec can take the following forms:
11089
11090 MatchSpecList:
11091 A list of match specifications. The matching is done on the
11092 list [Receiver, Msg]. Receiver is the process or port iden‐
11093 tity of the receiver and Msg is the message term. The pid of
11094 the sending process can be accessed with the guard function
11095 self/0. An empty list is the same as true. For more informa‐
11096 tion, see section Match Specifications in Erlang in the
11097 User's Guide.
11098
11099 true:
11100 Enables tracing for all sent messages (from send traced pro‐
11101 cesses). Any match specification is removed. This is the de‐
11102 fault.
11103
11104 false:
11105 Disables tracing for all sent messages. Any match specifica‐
11106 tion is removed.
11107
11108 Argument FlagList must be [] for send tracing.
11109
11110 The return value is always 1.
11111
11112 Examples:
11113
11114 Only trace messages to a specific process Pid:
11115
11116 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
11117 1
11118
11119 Only trace messages matching {reply, _}:
11120
11121 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
11122 1
11123
11124 Only trace messages sent to the sender itself:
11125
11126 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
11127 1
11128
11129 Only trace messages sent to other nodes:
11130
11131 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
11132 1
11133
11134 Note:
11135 A match specification for send trace can use all guard and body
11136 functions except caller.
11137
11138
11139 Fails by raising an error exception with an error reason of:
11140
11141 badarg:
11142 If an argument is invalid.
11143
11144 system_limit:
11145 If a match specification passed as argument has excessive
11146 nesting which causes scheduler stack exhaustion for the
11147 scheduler that the calling process is executing on. Sched‐
11148 uler stack size can be configured when starting the runtime
11149 system.
11150
11151 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
11152 integer() >= 0
11153
11154 Types:
11155
11156 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11157 trace_match_spec() =
11158 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11159 match_variable() = atom()
11160 Approximation of '$1' | '$2' | '$3' | ...
11161
11162 Sets trace pattern for message receiving. Must be combined with
11163 erlang:trace/3 to set the 'receive' trace flag for one or more
11164 processes. By default all messages received by 'receive' traced
11165 processes are traced. To limit traced receive events based on
11166 the message content, the sender and/or the receiver, use er‐
11167 lang:trace_pattern/3.
11168
11169 Argument MatchSpec can take the following forms:
11170
11171 MatchSpecList:
11172 A list of match specifications. The matching is done on the
11173 list [Node, Sender, Msg]. Node is the node name of the
11174 sender. Sender is the process or port identity of the
11175 sender, or the atom undefined if the sender is not known
11176 (which can be the case for remote senders). Msg is the mes‐
11177 sage term. The pid of the receiving process can be accessed
11178 with the guard function self/0. An empty list is the same as
11179 true. For more information, see section Match Specifica‐
11180 tions in Erlang in the User's Guide.
11181
11182 true:
11183 Enables tracing for all received messages (to 'receive'
11184 traced processes). Any match specification is removed. This
11185 is the default.
11186
11187 false:
11188 Disables tracing for all received messages. Any match speci‐
11189 fication is removed.
11190
11191 Argument FlagList must be [] for receive tracing.
11192
11193 The return value is always 1.
11194
11195 Examples:
11196
11197 Only trace messages from a specific process Pid:
11198
11199 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
11200 1
11201
11202 Only trace messages matching {reply, _}:
11203
11204 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
11205 1
11206
11207 Only trace messages from other nodes:
11208
11209 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
11210 1
11211
11212 Note:
11213 A match specification for 'receive' trace can use all guard and
11214 body functions except caller, is_seq_trace, get_seq_token,
11215 set_seq_token, enable_trace, disable_trace, trace, silent, and
11216 process_dump.
11217
11218
11219 Fails by raising an error exception with an error reason of:
11220
11221 badarg:
11222 If an argument is invalid.
11223
11224 system_limit:
11225 If a match specification passed as argument has excessive
11226 nesting which causes scheduler stack exhaustion for the
11227 scheduler that the calling process is executing on. Sched‐
11228 uler stack size can be configured when starting the runtime
11229 system.
11230
11231 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
11232 integer() >= 0
11233
11234 Types:
11235
11236 MFA = trace_pattern_mfa()
11237 MatchSpec =
11238 (MatchSpecList :: trace_match_spec()) |
11239 boolean() |
11240 restart | pause
11241 FlagList = [trace_pattern_flag()]
11242 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11243 trace_match_spec() =
11244 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11245 trace_pattern_flag() =
11246 global | local | meta |
11247 {meta, Pid :: pid()} |
11248 {meta, TracerModule :: module(), TracerState :: term()} |
11249 call_count | call_time
11250 match_variable() = atom()
11251 Approximation of '$1' | '$2' | '$3' | ...
11252
11253 Enables or disables call tracing for one or more functions. Must
11254 be combined with erlang:trace/3 to set the call trace flag for
11255 one or more processes.
11256
11257 Conceptually, call tracing works as follows. Inside the Erlang
11258 virtual machine, a set of processes and a set of functions are
11259 to be traced. If a traced process calls a traced function, the
11260 trace action is taken. Otherwise, nothing happens.
11261
11262 To add or remove one or more processes to the set of traced pro‐
11263 cesses, use erlang:trace/3.
11264
11265 To add or remove functions to the set of traced functions, use
11266 erlang:trace_pattern/3.
11267
11268 The BIF erlang:trace_pattern/3 can also add match specifications
11269 to a function. A match specification comprises a pattern that
11270 the function arguments must match, a guard expression that must
11271 evaluate to true, and an action to be performed. The default ac‐
11272 tion is to send a trace message. If the pattern does not match
11273 or the guard fails, the action is not executed.
11274
11275 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
11276 ity}, or the atom on_load (described below). It can be the mod‐
11277 ule, function, and arity for a function (or a BIF in any mod‐
11278 ule). The atom '_' can be used as a wildcard in any of the fol‐
11279 lowing ways:
11280
11281 {Module,Function,'_'}:
11282 All functions of any arity named Function in module Module.
11283
11284 {Module,'_','_'}:
11285 All functions in module Module.
11286
11287 {'_','_','_'}:
11288 All functions in all loaded modules.
11289
11290 Other combinations, such as {Module,'_',Arity}, are not allowed.
11291 Local functions match wildcards only if option local is in
11292 FlagList.
11293
11294 If argument MFA is the atom on_load, the match specification and
11295 flag list are used on all modules that are newly loaded.
11296
11297 Argument MatchSpec can take the following forms:
11298
11299 false:
11300 Disables tracing for the matching functions. Any match spec‐
11301 ification is removed.
11302
11303 true:
11304 Enables tracing for the matching functions. Any match speci‐
11305 fication is removed.
11306
11307 MatchSpecList:
11308 A list of match specifications. An empty list is equivalent
11309 to true. For a description of match specifications, see sec‐
11310 tion Match Specifications in Erlang in the User's Guide.
11311
11312 restart:
11313 For the FlagList options call_count and call_time: restarts
11314 the existing counters. The behavior is undefined for other
11315 FlagList options.
11316
11317 pause:
11318 For the FlagList options call_count and call_time: pauses
11319 the existing counters. The behavior is undefined for other
11320 FlagList options.
11321
11322 Parameter FlagList is a list of options. The following are the
11323 valid options:
11324
11325 global:
11326 Turns on or off call tracing for global function calls (that
11327 is, calls specifying the module explicitly). Only exported
11328 functions match and only global calls generate trace mes‐
11329 sages. This is the default.
11330
11331 local:
11332 Turns on or off call tracing for all types of function
11333 calls. Trace messages are sent whenever any of the specified
11334 functions are called, regardless of how they are called. If
11335 flag return_to is set for the process, a return_to message
11336 is also sent when this function returns to its caller.
11337
11338 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
11339 Turns on or off meta-tracing for all types of function
11340 calls. Trace messages are sent to the tracer whenever any of
11341 the specified functions are called. If no tracer is speci‐
11342 fied, self() is used as a default tracer process.
11343
11344 Meta-tracing traces all processes and does not care about
11345 the process trace flags set by erlang:trace/3, the trace
11346 flags are instead fixed to [call, timestamp].
11347
11348 The match specification function {return_trace} works with
11349 meta-trace and sends its trace message to the same tracer.
11350
11351 call_count:
11352 Starts (MatchSpec == true) or stops (MatchSpec == false)
11353 call count tracing for all types of function calls. For ev‐
11354 ery function, a counter is incremented when the function is
11355 called, in any process. No process trace flags need to be
11356 activated.
11357
11358 If call count tracing is started while already running, the
11359 count is restarted from zero. To pause running counters, use
11360 MatchSpec == pause. Paused and running counters can be
11361 restarted from zero with MatchSpec == restart.
11362
11363 To read the counter value, use erlang:trace_info/2.
11364
11365 call_time:
11366 Starts (MatchSpec == true) or stops (MatchSpec == false)
11367 call time tracing for all types of function calls. For every
11368 function, a counter is incremented when the function is
11369 called. Time spent in the function is accumulated in two
11370 other counters, seconds and microseconds. The counters are
11371 stored for each call traced process.
11372
11373 If call time tracing is started while already running, the
11374 count and time restart from zero. To pause running counters,
11375 use MatchSpec == pause. Paused and running counters can be
11376 restarted from zero with MatchSpec == restart.
11377
11378 To read the counter value, use erlang:trace_info/2.
11379
11380 The options global and local are mutually exclusive, and global
11381 is the default (if no options are specified). The options
11382 call_count and meta perform a kind of local tracing, and cannot
11383 be combined with global. A function can be globally or locally
11384 traced. If global tracing is specified for a set of functions,
11385 then local, meta, call time, and call count tracing for the
11386 matching set of local functions is disabled, and conversely.
11387
11388 When disabling trace, the option must match the type of trace
11389 set on the function. That is, local tracing must be disabled
11390 with option local and global tracing with option global (or no
11391 option), and so on.
11392
11393 Part of a match specification list cannot be changed directly.
11394 If a function has a match specification, it can be replaced with
11395 a new one. To change an existing match specification, use the
11396 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
11397 cation.
11398
11399 Returns the number of functions matching argument MFA. This is
11400 zero if none matched.
11401
11402 Fails by raising an error exception with an error reason of:
11403
11404 badarg:
11405 If an argument is invalid.
11406
11407 system_limit:
11408 If a match specification passed as argument has excessive
11409 nesting which causes scheduler stack exhaustion for the
11410 scheduler that the calling process is executing on. Sched‐
11411 uler stack size can be configured when starting the runtime
11412 system.
11413
11414 trunc(Number) -> integer()
11415
11416 Types:
11417
11418 Number = number()
11419
11420 Truncates the decimals of Number, for example:
11421
11422 > trunc(5.7).
11423 5
11424
11425 > trunc(-5.7).
11426 -5
11427
11428 > trunc(5).
11429 5
11430
11431 > trunc(36028797018963969.0).
11432 36028797018963968
11433
11434 In the last example, trunc(36028797018963969.0) evaluates to
11435 36028797018963968. The reason for this is that the number
11436 36028797018963969.0 cannot be represented exactly as a float
11437 value. Instead, the float literal is represented as
11438 36028797018963968.0, which is the closest number that can be
11439 represented exactly as a float value. See Representation of
11440 Floating Point Numbers for additional information.
11441
11442 Allowed in guard tests.
11443
11444 tuple_size(Tuple) -> integer() >= 0
11445
11446 Types:
11447
11448 Tuple = tuple()
11449
11450 Returns an integer that is the number of elements in Tuple, for
11451 example:
11452
11453 > tuple_size({morni, mulle, bwange}).
11454 3
11455
11456 Allowed in guard tests.
11457
11458 tuple_to_list(Tuple) -> [term()]
11459
11460 Types:
11461
11462 Tuple = tuple()
11463
11464 Returns a list corresponding to Tuple. Tuple can contain any Er‐
11465 lang terms. Example:
11466
11467 > tuple_to_list({share, {'Ericsson_B', 163}}).
11468 [share,{'Ericsson_B',163}]
11469
11470 unalias(Alias) -> boolean()
11471
11472 Types:
11473
11474 Alias = reference()
11475
11476 Deactivate the alias Alias previously created by the calling
11477 process. An alias can for example be created via alias/0, or
11478 monitor/3. unalias/1 will always deactivate the alias regardless
11479 of options used when creating the alias.
11480
11481 Returns true if Alias was a currently active alias for current
11482 processes; otherwise, false.
11483
11484 For more information on process aliases see the Process Aliases
11485 section of the Erlang Reference Manual .
11486
11487 erlang:unique_integer() -> integer()
11488
11489 Generates and returns an integer unique on current runtime sys‐
11490 tem instance. The same as calling erlang:unique_integer([]).
11491
11492 erlang:unique_integer(ModifierList) -> integer()
11493
11494 Types:
11495
11496 ModifierList = [Modifier]
11497 Modifier = positive | monotonic
11498
11499 Generates and returns an integer unique on current runtime sys‐
11500 tem instance. The integer is unique in the sense that this BIF,
11501 using the same set of modifiers, does not return the same inte‐
11502 ger more than once on the current runtime system instance. Each
11503 integer value can of course be constructed by other means.
11504
11505 By default, when [] is passed as ModifierList, both negative and
11506 positive integers can be returned. This to use the range of in‐
11507 tegers that do not need heap memory allocation as much as possi‐
11508 ble. By default the returned integers are also only guaranteed
11509 to be unique, that is, any returned integer can be smaller or
11510 larger than previously returned integers.
11511
11512 Modifiers:
11513
11514 positive:
11515 Returns only positive integers.
11516
11517 Notice that by passing the positive modifier you will get
11518 heap allocated integers (bignums) quicker.
11519
11520 monotonic:
11521 Returns strictly monotonically increasing integers corre‐
11522 sponding to creation time. That is, the integer returned is
11523 always larger than previously returned integers on the cur‐
11524 rent runtime system instance.
11525
11526 These values can be used to determine order between events
11527 on the runtime system instance. That is, if both X = er‐
11528 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
11529 ger([monotonic]) are executed by different processes (or the
11530 same process) on the same runtime system instance and X < Y,
11531 we know that X was created before Y.
11532
11533 Warning:
11534 Strictly monotonically increasing values are inherently quite
11535 expensive to generate and scales poorly. This is because the
11536 values need to be synchronized between CPU cores. That is, do
11537 not pass the monotonic modifier unless you really need
11538 strictly monotonically increasing values.
11539
11540
11541 All valid Modifiers can be combined. Repeated (valid) Modifiers
11542 in the ModifierList are ignored.
11543
11544 Note:
11545 The set of integers returned by erlang:unique_integer/1 using
11546 different sets of Modifiers will overlap. For example, by call‐
11547 ing unique_integer([monotonic]), and unique_integer([positive,
11548 monotonic]) repeatedly, you will eventually see some integers
11549 that are returned by both calls.
11550
11551
11552 Failures:
11553
11554 badarg:
11555 if ModifierList is not a proper list.
11556
11557 badarg:
11558 if Modifier is not a valid modifier.
11559
11560 erlang:universaltime() -> DateTime
11561
11562 Types:
11563
11564 DateTime = calendar:datetime()
11565
11566 Returns the current date and time according to Universal Time
11567 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
11568 Minute, Second}} if supported by the underlying OS. Otherwise
11569 erlang:universaltime() is equivalent to erlang:localtime(). The
11570 return value is based on the OS System Time. Example:
11571
11572 > erlang:universaltime().
11573 {{1996,11,6},{14,18,43}}
11574
11575 erlang:universaltime_to_localtime(Universaltime) -> Localtime
11576
11577 Types:
11578
11579 Localtime = Universaltime = calendar:datetime()
11580
11581 Converts Universal Time Coordinated (UTC) date and time to local
11582 date and time in the form {{Year, Month, Day}, {Hour, Minute,
11583 Second}} if supported by the underlying OS. Otherwise no conver‐
11584 sion is done, and Universaltime is returned. Example:
11585
11586 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
11587 {{1996,11,7},{15,18,43}}
11588
11589 Failure: badarg if Universaltime denotes an invalid date and
11590 time.
11591
11592 unlink(Id) -> true
11593
11594 Types:
11595
11596 Id = pid() | port()
11597
11598 Removes a link between the calling process and another process
11599 or a port identified by Id. We will from here on call the iden‐
11600 tified process or port unlinkee.
11601
11602 A link can be set up using the link/1 BIF. For more information
11603 on links and exit signals due to links, see the Processes chap‐
11604 ter in the Erlang Reference Manual :
11605
11606 * Links
11607
11608 * Sending Exit Signals
11609
11610 * Receiving Exit Signals
11611
11612 Once unlink(Id) has returned, it is guaranteed that the link be‐
11613 tween the caller and the unlinkee has no effect on the caller in
11614 the future (unless the link is setup again). Note that if the
11615 caller is trapping exits, an {'EXIT', Id, ExitReason} message
11616 due to the link may have been placed in the message queue of the
11617 caller before the unlink(Id) call completed. Also note that the
11618 {'EXIT', Id, ExitReason} message may be the result of the link,
11619 but may also be the result of the unlikee sending the caller an
11620 exit signal by calling the exit/2 BIF. Therefore, it may or may
11621 not be appropriate to clean up the message queue after a call to
11622 unlink(Id) as follows, when trapping exits:
11623
11624 unlink(Id),
11625 receive
11626 {'EXIT', Id, _} ->
11627 true
11628 after 0 ->
11629 true
11630 end
11631
11632 The link removal is performed asynchronously. If such a link
11633 does not exist, nothing is done. A detailed description of the
11634 link protocol can be found in the Distribution Protocol chapter
11635 of the ERTS User's Guide .
11636
11637 Failure: badarg if Id does not identify a process or a node lo‐
11638 cal port.
11639
11640 unregister(RegName) -> true
11641
11642 Types:
11643
11644 RegName = atom()
11645
11646 Removes the registered name RegName associated with a process
11647 identifier or a port identifier from the name registry. For ex‐
11648 ample:
11649
11650 > unregister(db).
11651 true
11652
11653 Keep in mind that you can still receive signals associated with
11654 the registered name after it has been unregistered as the sender
11655 may have looked up the name before sending to it.
11656
11657 Users are advised not to unregister system processes.
11658
11659 Failure: badarg if RegName is not a registered name.
11660
11661 whereis(RegName) -> pid() | port() | undefined
11662
11663 Types:
11664
11665 RegName = atom()
11666
11667 Returns the process identifier or port identifier with the reg‐
11668 istered name RegName from the name registry. Returns undefined
11669 if the name is not registered. Example:
11670
11671 > whereis(db).
11672 <0.43.0>
11673
11674 erlang:yield() -> true
11675
11676 Tries to give other processes with the same or higher priority
11677 (if any) a chance to execute before returning. There is no guar‐
11678 antee that any other process runs between the invocation and re‐
11679 turn of erlang:yield/0.
11680
11681 See the documentation for receive-after expressions for how to
11682 make the current process sleep for a specific number of mil‐
11683 liseconds.
11684
11685 Warning:
11686 There is seldom or never any need to use this BIF. Using this
11687 BIF without a thorough grasp of how the scheduler works can
11688 cause performance degradation. The current implementation of
11689 this function puts the current process last in the current
11690 scheduler's queue for processes of the same priority as the cur‐
11691 rent process.
11692
11693
11694
11695
11696Ericsson AB erts 12.1.5 erlang(3)