From c431a065ba515d27830f01c852f70940efb3003b Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 2 Jul 2015 11:13:32 +0200 Subject: ose: Remove all code related to the OSE port The OSE port is no longer supported and this commit removed it and any changes related to it. The things that were general improvements have been left in the code. --- erts/doc/src/driver_entry.xml | 8 ++------ erts/doc/src/erl_driver.xml | 6 ++---- erts/doc/src/erlang.xml | 2 +- erts/doc/src/run_erl.xml | 2 +- 4 files changed, 6 insertions(+), 12 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml index 30772c68fe..32fc9e13a4 100644 --- a/erts/doc/src/driver_entry.xml +++ b/erts/doc/src/driver_entry.xml @@ -246,14 +246,10 @@ typedef struct erl_drv_entry { something that the WaitForMultipleObjects API function understands). (Some trickery in the emulator allows more than the built-in limit of 64 Events to be used.)

-

On Enea OSE the event is one or more signals that can - be retrieved using erl_drv_ose_get_signal.

To use this with threads and asynchronous routines, create a - pipe on unix, an Event on Windows or a unique signal number on - Enea OSE. When the routine + pipe on unix and an Event on Windows. When the routine completes, write to the pipe (use SetEvent on - Windows or send a message to the emulator process on Enea OSE), - this will make the emulator call + Windows), this will make the emulator call ready_input or ready_output.

Spurious events may happen. That is, calls to ready_input or ready_output even though no real events are signaled. In diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 1f7fe0f961..3bf18ae8d0 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1044,9 +1044,7 @@ typedef struct ErlIOVec { select/poll can use). On windows, the Win32 API function WaitForMultipleObjects is used. This places other restrictions on the event object. - Refer to the Win32 SDK documentation. - On Enea OSE, the receive function is used. See the for more details.

+ Refer to the Win32 SDK documentation.

The on parameter should be 1 for setting events and 0 for clearing them.

The mode argument is a bitwise-or combination of @@ -1058,7 +1056,7 @@ typedef struct ErlIOVec { ready_output.

-

Some OS (Windows and Enea OSE) do not differentiate between read and write events. +

Some OS (Windows) do not differentiate between read and write events. The call-back for a fired event then only depends on the value of mode.

ERL_DRV_USE specifies if we are using the event object or if we want to close it. diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 37f0aa289e..e77532463e 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -1054,7 +1054,7 @@ Print a term on standard output

Prints a text representation of Term on the standard - output. On OSE the term is printed to the ramlog.

+ output.

This BIF is intended for debugging only.

 diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml index 0a5b2c6136..faec3c68c1 100644 --- a/erts/doc/src/run_erl.xml +++ b/erts/doc/src/run_erl.xml @@ -59,7 +59,7 @@ first argument to run_erl on the command line. pipe_dir This is where to put the named pipe, usually - on Unix or on OSE. It shall be suffixed by a (slash), + . It shall be suffixed by a (slash), i.e. not , but . log_dir This is where the log files are written. There will be one -- cgit v1.2.3 From 6e93fb788aebb9050da2166749b41ff54197e049 Mon Sep 17 00:00:00 2001 From: Kostis Sagonas Date: Thu, 7 May 2015 14:43:02 +0200 Subject: Take out automatic insertion of 'undefined' from typed record fields Background ----------- In record fields with a type declaration but without an initializer, the Erlang parser inserted automatically the singleton type 'undefined' to the list of declared types, if that value was not present there. I.e. the record declaration: -record(rec, {f1 :: float(), f2 = 42 :: integer(), f3 :: some_mod:some_typ()}). was translated by the parser to: -record(rec, {f1 :: float() | 'undefined', f2 = 42 :: integer(), f3 :: some_mod:some_typ() | 'undefined'}). The rationale for this was that creation of a "dummy" #rec{} record should not result in a warning from dialyzer that e.g. the implicit initialization of the #rec.f1 field violates its type declaration. Problems --------- This seemingly innocent action has some unforeseen consequences. For starters, there is no way for programmers to declare that e.g. only floats make sense for the f1 field of #rec{} records when there is no `obvious' default initializer for this field. (This also affects tools like PropEr that use these declarations produced by the Erlang parser to generate random instances of records for testing purposes.) It also means that dialyzer does not warn if e.g. an is_atom/1 test or something more exotic like an atom_to_list/1 call is performed on the value of the f1 field. Similarly, there is no way to extend dialyzer to warn if it finds record constructions where f1 is not initialized to some float. Last but not least, it is semantically problematic when the type of the field is an opaque type: creating a union of an opaque and a structured type is very problematic for analysis because it fundamentally breaks the opacity of the term at that point. Change ------- To solve these problems the parser will not automatically insert the 'undefined' value anymore; instead the user has the option to choose the places where this value makes sense (for the field) and where it does not and insert the | 'undefined' there manually. Consequences of this change ---------------------------- This change means that dialyzer will issue a warning for all places where records with uninitialized fields are created and those fields have a declared type that is incompatible with 'undefined' (e.g. float()). This warning can be suppressed easily by adding | 'undefined' to the type of this field. This also adds documentation that the user really intends to create records where this field is uninitialized. --- erts/doc/src/absform.xml | 6 ------ 1 file changed, 6 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index df2553ced3..49fe784d06 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -246,12 +246,6 @@ Rep(V) = . If V is , then Rep(V) = . - If V is , where is - an atom and is a type and it does not contain - syntactically, then Rep(V) = - . - Note that if is an annotated type, it will be wrapped in - parentheses. If V is , where is an atom and is a type, then Rep(V) = . -- cgit v1.2.3 From 285b4fa13914dc4748c1020213a9c65cad3d2738 Mon Sep 17 00:00:00 2001 From: Serge Aleynikov Date: Tue, 2 Jun 2015 08:44:23 -0400 Subject: erts: Add {line_delimiter, byte()} option to inet:setopts/2 A new {line_delimiter, byte()} option allows line-oriented TCP-based protocols to use a custom line delimiting character. It is to be used in conjunction with {packet, line}. This option also works with erlang:decode_packet/3 when its first argument is 'line'. --- erts/doc/src/erlang.xml | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 0492924164..1963b27915 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -933,6 +933,10 @@ if packet_size itself is not set. This use is only intended for backward compatibility.

 + {line_delimiter, 0 ≤ char() ≤ 255} +

For packet type line, sets delimiting character. + Default $\n.

+

Examples:

-- 
cgit v1.2.3


From 8377afdf5f56d018a1b439bbccc918ce123a834b Mon Sep 17 00:00:00 2001
From: Ingela Anderton Andin 
Date: Fri, 16 Oct 2015 11:43:20 +0200
Subject: erts: Clarify documentation

---
 erts/doc/src/erlang.xml | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 1963b27915..70d000f763 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -874,10 +874,10 @@
           
           line
           
-            
A packet is a line terminated with newline. The
-              newline character is included in the returned packet
-              unless the line was truncated according to option
-              line_length.
 
+            
A packet is a line terminated by a delimiter byte,
+            default is the latin1 newline character. The delimiter
+            byte is included in the returned packet unless the line
+            was truncated according to option line_length.

           
           asn1 | cdr | sunrm | fcgi | tpkt
           
@@ -933,9 +933,9 @@
                 if packet_size itself is not set. This use is
                 only intended for backward compatibility.

               
-              {line_delimiter, 0 ≤ char() ≤ 255}
-              
For packet type line, sets delimiting character.
-                Default $\n.

+              {line_delimiter, 0 =< byte() =< 255}
+              
For packet type line, sets the delimiting byte.
+                Default is the latin1 character $\n.

               
             
         
Examples:

-- 
cgit v1.2.3


From 3ac08f9b668613a4292436979eacc61863c2ab94 Mon Sep 17 00:00:00 2001
From: Rickard Green 
Date: Wed, 16 Sep 2015 15:02:50 +0200
Subject: Fragmented young heap generation and off_heap_message_queue option

* The youngest generation of the heap can now consist of multiple
  blocks. Heap fragments and message fragments are added to the
  youngest generation when needed without triggering a GC. After
  a GC the youngest generation is contained in one single block.
* The off_heap_message_queue process flag has been added. When
  enabled all message data in the queue is kept off heap. When
  a message is selected from the queue, the message fragment (or
  heap fragment) containing the actual message is attached to the
  youngest generation. Messages stored off heap is not part of GC.
---
 erts/doc/src/erl.xml    | 15 ++++++++++
 erts/doc/src/erlang.xml | 77 +++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 90 insertions(+), 2 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index b0322b7d43..8c1be4dff5 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -1335,6 +1335,21 @@
           error_logger(3)
           for further information.

       
+      
+      
+        
Default process flag settings.

+        
+          +xohmq true|false
+          

+	    Sets the default value for the process flag
+	    off_heap_message_queue. If +xohmq is not
+	    passed, false will be the default. For more information,
+	    see the documentation of
+            process_flag(off_heap_message_queue,
+	    OHMQ).
+	  

+	
+      
       
       
         
Miscellaneous flags.

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index e77532463e..9426d30390 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -4058,8 +4058,46 @@ os_prompt%
process.

Returns the old value of the flag.

+ + Set process flag off_heap_message_queue for the calling process + +

This flag determines how messages in the message queue + are stored. When the flag is:

+ + true +

+ All messages in the message queue will be stored + outside of the process heap. This implies that no + messages in the message queue will be part of a garbage + collection of the process. +

+ false +

+ Messages may be placed either on the heap or outside + of the heap. +

+ +

+ If the process potentially may get a hugh amount of messages, + you are recommended to set the flag to true. This since + a garbage collection with lots of messages placed on the heap + may become extremly expensive. Performance of the actual + message passing is however generally better when setting the + flag to false. +

+

+ When changing this flag from false to true, + all messages in the message queue are moved off heap. This + work has been initiated but not completed when this function + call returns. +

+

Returns the old value of the flag.

+ + + + Set process flag priority for the calling process @@ -4138,7 +4176,7 @@ os_prompt% - + Set process flag save_calls for the calling process

N must be an integer in the interval 0..10000. @@ -4162,7 +4200,7 @@ os_prompt% - + Set process flag sensitive for the calling process

Set or clear the sensitive flag for the current process. @@ -4408,6 +4446,14 @@ os_prompt% monitor by name, the list item is {process, {RegName, Node}}.

+ {off_heap_message_queue, OHMQ} + +

Returns the current state of the off_heap_message_queue + process flag. OHMQ is either true, or + false. For more information, see the documentation of + process_flag(off_heap_message_queue, + OHMQ).

+ {priority, Level}

Level is the current priority level for @@ -5067,6 +5113,7 @@ true + Create a new process with a fun as entry point

Returns the pid of a new process started by the application @@ -5081,6 +5128,7 @@ true + Create a new process with a fun as entry point on a given node

Returns the pid of a new process started by the application @@ -5093,6 +5141,7 @@ true + Create a new process with a function as entry point

Works exactly like @@ -5188,6 +5237,18 @@ true fine-tuning an application and to measure the execution time with various VSize values.

 + {off_heap_message_queue, OHMQ} + +

Sets the state of the off_heap_message_queue process + flag. OHMQ should be either true, or + false. The default off_heap_message_queue process + flag is determined by the + +xohmq erl + command line argument. For more information, see the + documentation of + process_flag(off_heap_message_queue, + OHMQ).

+ @@ -5195,6 +5256,7 @@ true + Create a new process with a function as entry point on a given node

Returns the pid of a new process started by the application @@ -6224,6 +6286,7 @@ ok + Information about the system

Returns various information about the current system @@ -6614,6 +6677,16 @@ ok

Returns a string containing the erlang NIF version used by the runtime system. It will be on the form "<major ver>.<minor ver>".

+ off_heap_message_queue + +

Returns the default value of the off_heap_message_queue + process flag which is either true or false. This + default is set by the erl command line argument + +xohmq. For more information on the + off_heap_message_queue process flag, see documentation of + process_flag(off_heap_message_queue, + OHMQ).

+ otp_release

Returns a string containing the OTP release number of the -- cgit v1.2.3 From 9d0a5bf2c1cc564fd38268cbb5313cd8813ea138 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Mon, 16 Nov 2015 14:57:12 +0100 Subject: erts: Add garbage_collection_info to process_info/2 This info request returns greater details about the current gc state. This info is not included in the default process_info/1 as it would clutter the default printout with too much information. --- erts/doc/src/erlang.xml | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 2e82bb62a9..e4d3533c75 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4621,6 +4621,17 @@ os_prompt% The content of GCInfo can be changed without prior notice.

 + {garbage_collection_info, GCInfo} + +

GCInfo is a list containing miscellaneous + detailed information about garbage collection for this process. + The content of GCInfo can be changed without + prior notice. + See gc_start in + erlang:trace/3 for details about + what each item means. +

+ {group_leader, GroupLeader}

GroupLeader is group leader for the I/O of -- cgit v1.2.3 From 19c4689eea86f26c5af9b8f712c227ce4f62310b Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 24 Nov 2015 15:57:55 +0100 Subject: Replace off_heap_message_queue option with message_queue_data option The message_queue_data option can have the values - off_heap - on_heap - mixed --- erts/doc/src/erl.xml | 10 +++--- erts/doc/src/erlang.xml | 94 +++++++++++++++++++++++++++++++------------------ 2 files changed, 65 insertions(+), 39 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index c4eb0e16ec..b6fa4c254c 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -1338,14 +1338,14 @@

Default process flag settings.

- +xohmq true|false + +xmqd off_heap|on_heap|mixed

Sets the default value for the process flag - off_heap_message_queue. If +xohmq is not - passed, false will be the default. For more information, + message_queue_data. If +xmqd is not + passed, mixed will be the default. For more information, see the documentation of - process_flag(off_heap_message_queue, - OHMQ). + process_flag(message_queue_data, + MQD).

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 2e82bb62a9..6ed03f3dfc 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -58,6 +58,12 @@ + + +

See erlang:process_flag(message_queue_data, MQD).

+ + +

See erlang:timestamp/0.

@@ -4280,39 +4286,52 @@ os_prompt%

Returns the old value of the flag.

 - + - Set process flag off_heap_message_queue for the calling process + Set process flag message_queue_data for the calling process +

This flag determines how messages in the message queue are stored. When the flag is:

- true + off_heap

All messages in the message queue will be stored outside of the process heap. This implies that no messages in the message queue will be part of a garbage collection of the process.

- false + on_heap +

+ All messages in the message queue will eventually be + placed on heap. They may however temporarily be stored + off heap. This is how messages always have been stored + up until ERTS version 8.0. +

+ mixed

Messages may be placed either on the heap or outside of the heap.

+

+ The default message_queue_data process flag is determined + by the +xmqd + erl command line argument. +

If the process potentially may get a hugh amount of messages, - you are recommended to set the flag to true. This since - a garbage collection with lots of messages placed on the heap - may become extremly expensive. Performance of the actual - message passing is however generally better when setting the - flag to false. + you are recommended to set the flag to off_heap. This + since a garbage collection with lots of messages placed on + the heap may become extremly expensive and the process may + consume large amounts of memory. Performance of the + actual message passing is however generally better when not + using the off_heap flag.

- When changing this flag from false to true, - all messages in the message queue are moved off heap. This - work has been initiated but not completed when this function + When changing this flag messages will be moved. This work + has been initiated but not completed when this function call returns.

Returns the old value of the flag.

@@ -4478,6 +4497,7 @@ os_prompt% +

Returns a list containing InfoTuples with miscellaneous information about the process identified by @@ -4530,6 +4550,7 @@ os_prompt% +

Returns information about the process identified by Pid, as specified by @@ -4698,13 +4719,14 @@ os_prompt% monitor by name, the list item is {process, {RegName, Node}}.

- {off_heap_message_queue, OHMQ} + {message_queue_data, MQD} -

Returns the current state of the off_heap_message_queue - process flag. OHMQ is either true, or - false. For more information, see the documentation of - process_flag(off_heap_message_queue, - OHMQ).

+

Returns the current state of the message_queue_data + process flag. MQD is either off_heap, + on_heap, or mixed. For more information, see the + documentation of + process_flag(message_queue_data, + MQD).

 {priority, Level} @@ -5474,6 +5496,7 @@ true Creates a new process with a fun as entry point. +

Returns the process identifier (pid) of a new process @@ -5490,6 +5513,7 @@ true Creates a new process with a fun as entry point on a given node. +

Returns the process identifier (pid) of a new process started @@ -5505,6 +5529,7 @@ true Creates a new process with a function as entry point. +

Works as @@ -5607,17 +5632,17 @@ true fine-tuning an application and to measure the execution time with various VSize values.

 - {off_heap_message_queue, OHMQ} + {message_queue_data, MQD} -

Sets the state of the off_heap_message_queue process - flag. OHMQ should be either true, or - false. The default off_heap_message_queue process - flag is determined by the - +xohmq erl +

Sets the state of the message_queue_data process + flag. MQD should be either off_heap, + on_heap, or mixed. The default + message_queue_data process flag is determined by the + +xmqd erl command line argument. For more information, see the documentation of - process_flag(off_heap_message_queue, - OHMQ).

+ process_flag(message_queue_data, + MQD).

 @@ -5627,6 +5652,7 @@ true Creates a new process with a function as entry point on a given node. +

Returns the process identifier (pid) of a new process started @@ -7106,15 +7132,15 @@ ok used by the runtime system. It is on the form "<major ver>.<minor ver>".

- off_heap_message_queue + message_queue_data -

Returns the default value of the off_heap_message_queue - process flag which is either true or false. This - default is set by the erl command line argument - +xohmq. For more information on the - off_heap_message_queue process flag, see documentation of - process_flag(off_heap_message_queue, - OHMQ).

+

Returns the default value of the message_queue_data + process flag which is either off_heap, on_heap, or mixed. + This default is set by the erl command line argument + +xmqd. For more information on the + message_queue_data process flag, see documentation of + process_flag(message_queue_data, + MQD).

 otp_release -- cgit v1.2.3 From 41d147339c65d2b6dfcf60c1e63482612774bede Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Thu, 10 Dec 2015 15:45:55 +0100 Subject: Eliminate mentions of 'random' in documentation --- erts/doc/src/init.xml | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index fe26df61f7..2a33096d04 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -247,10 +247,7 @@ Expr during system initialization. If any of these steps fail (syntax error, parse error or exception during evaluation), Erlang stops with an error message. Here is an - example that seeds the random number generator:

- 
-% erl -eval '{X,Y,Z} = now(), random:seed(X,Y,Z).'
-

This example uses Erlang as a hexadecimal calculator:

+ example that uses Erlang as a hexadecimal calculator:

 % erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\
 -s erlang halt
-- 
cgit v1.2.3


From 4b98e710b9c45481c1cdc7a4ee68f7ce7fca908a Mon Sep 17 00:00:00 2001
From: Lukas Larsson 
Date: Mon, 13 Jul 2015 15:38:41 +0200
Subject: erts: Add support for asynchronous open_port

OTP-13086
---
 erts/doc/src/driver_entry.xml |  9 ++++++++-
 erts/doc/src/erl_driver.xml   | 28 ++++++++++++++++++++++++++++
 2 files changed, 36 insertions(+), 1 deletion(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index c802693977..ae7f264d0c 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -437,7 +437,14 @@ typedef struct erl_drv_entry {
 	  erl_drv_busy_msgq_limits()
 	  function.
           
-         
+          ERL_DRV_FLAG_USE_INIT_ACK
+          When this flag is given the linked-in driver has to manually
+          acknowledge that the port has been successfully started using 
+	  erl_drv_init_ack().
+          This allows the implementor to make the erlang:open_port exit with
+          badarg after some initial asynchronous initialization has been done.
+          
+        
       
       void *handle2
       
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index f7b4187b80..a2a1df37e5 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -2130,6 +2130,34 @@ ERL_DRV_MAP          int sz
       
     
 
+    
+      voiderl_drv_init_ack(ErlDrvPort port, ErlDrvData res)
+      Acknowledge the start of the port
+      
+        
+        
Arguments:

+        
+          port
+          The port handle of the port (driver instance) creating
+           doing the acknowledgment.
+	  
+          res
+          The result of the port initialization. This can be the same values
+          as the return value of start,
+          i.e any of the error codes or the ErlDrvData that is to be used for this
+          port.
+          
+        
+        

+          When this function is called the initiating erlang:open_port call is
+          returned as if the start
+          function had just been called. It can only be used when the
+          ERL_DRV_FLAG_USE_INIT_ACK
+          flag has been set on the linked-in driver.
+        

+      
+    
+
     
       interl_drv_thread_create(char *name,
 				      ErlDrvTid *tid,
-- 
cgit v1.2.3


From 91c1876f70870f450f7e8fd3b02f2396067e3cb8 Mon Sep 17 00:00:00 2001
From: Lukas Larsson 
Date: Tue, 14 Jul 2015 11:07:33 +0200
Subject: erts: Add erl_drv_set_pid

OTP-13087
---
 erts/doc/src/erl_driver.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index a2a1df37e5..ef6d69cbeb 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -2158,6 +2158,25 @@ ERL_DRV_MAP          int sz
       
     
 
+    
+      voiderl_drv_set_os_pid(ErlDrvPort port, ErlDrvSInt pid)
+      Set the os_pid for the port
+      
+        
+        
Arguments:

+        
+          port
+          The port handle of the port (driver instance) to set the pid on.
+	  
+          pid
+          The pid to set.
+        
+        

+          Set the os_pid seen when doing erlang:port_info/2 on this port.
+        

+      
+    
+
     
       interl_drv_thread_create(char *name,
 				      ErlDrvTid *tid,
-- 
cgit v1.2.3


From 566a7f4324376428f3f0f6a77bc57679f04ada78 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= 
Date: Wed, 16 Dec 2015 15:15:03 +0100
Subject: Clean up start of erl_prim_loader

The 'init' module fetches command line parameters and passes them
to erl_prim_loader:start/3.

The code can be simplified if 'init' calls a new
erl_prim_loader:start/0 function that itself fetches the necessary
command line parameters. Also remove the documentation for the start()
function, since it there is no way that it can be usefully called by
a user application.

While we are at it, also get rid of '-id' command line parameter,
which is fetched and stored but never actually used.
---
 erts/doc/src/erl_prim_loader.xml | 40 ++++------------------------------------
 1 file changed, 4 insertions(+), 36 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml
index db4f132609..6fdec8c89e 100644
--- a/erts/doc/src/erl_prim_loader.xml
+++ b/erts/doc/src/erl_prim_loader.xml
@@ -50,35 +50,8 @@
      -loader_debug are also experimental

 
   
-  
-    
-      
-    
-  
 
   
-    
-      
-      Start the Erlang low level loader
-      
-        
Starts the Erlang low level loader. This function is called
-          by the init process (and module). The init
-          process reads the command line flags -id Id,
-          -loader Loader, and -hosts Hosts. These are
-          the arguments supplied to the start/3 function.

-        
If -loader is not given, the default loader is
-          efile which tells the system to read from the file
-          system.

-        
If -loader is inet, the -id Id,
-          -hosts Hosts, and -setcookie Cookie flags must
-          also be supplied. Hosts identifies hosts which this
-          node can contact in order to load modules. One Erlang
-          runtime system with a erl_boot_server process must be
-          started on each of hosts given in Hosts in order to
-          answer the requests. See erl_boot_server(3).

-      
-    
     
       
       Get a file
@@ -189,17 +162,12 @@
         
Specifies which other Erlang nodes the inet loader
           can use. This flag is mandatory if the -loader inet
           flag is present. On each host, there must be on Erlang node
-          with the erl_boot_server which handles the load
-          requests. Hosts is a list of IP addresses (hostnames
+          with the erl_boot_server(3)
+	  which handles the load requests.
+	  Hosts is a list of IP addresses (hostnames
           are not acceptable).

       
-      -id Id
-      
-        
Specifies the identity of the Erlang runtime system. If
-          the system runs as a distributed node, Id must be
-          identical to the name supplied with the -sname or
-          -name distribution flags.

-      
       -setcookie Cookie
       
         
Specifies the cookie of the Erlang runtime system. This flag
-- 
cgit v1.2.3


From b74e7f4c1404a334be10c5d4a8b1ef5415405425 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= 
Date: Wed, 16 Dec 2015 14:38:55 +0100
Subject: erl_prim_loader doc: Remove mention of user supplied loader

Custom loaders are no longer supported. Most of the documentation
for them were removed in c8a7d2d7.
---
 erts/doc/src/erl_prim_loader.xml | 2 --
 1 file changed, 2 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml
index 6fdec8c89e..8f66e07ae1 100644
--- a/erts/doc/src/erl_prim_loader.xml
+++ b/erts/doc/src/erl_prim_loader.xml
@@ -60,8 +60,6 @@
           Filename is either an absolute file name or just the name
           of the file, for example "lists.beam". If an internal
           path is set to the loader, this path is used to find the file.
-          If a user supplied loader is used, the path can be stripped
-          off if it is obsolete, and the loader does not use a path.
           FullName is the complete name of the fetched file.
           Bin is the contents of the file as a binary.

 
-- 
cgit v1.2.3


From a96f36890da959bcb134ac4f6d24d5132e7bb5be Mon Sep 17 00:00:00 2001
From: Erlang/OTP 
Date: Thu, 17 Dec 2015 14:53:04 +0100
Subject: Update release notes

---
 erts/doc/src/notes.xml | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

(limited to 'erts/doc')

diff --git a/erts/doc/src/notes.xml b/erts/doc/src/notes.xml
index 5cb9bdb690..a726cc7b97 100644
--- a/erts/doc/src/notes.xml
+++ b/erts/doc/src/notes.xml
@@ -32,6 +32,27 @@
   
This document describes the changes made to the ERTS application.

 
 
+
Erts 7.2.1
+
+    
Fixed Bugs and Malfunctions
+      
+        
+          

+	    Revert "Fix erroneous splitting of emulator path"

+          

+	    Own Id: OTP-13202

+        
+        
+          

+	    Fix HiPE enabled emulator for FreeBSD.

+          

+	    Own Id: OTP-13204 Aux Id: pr926 

+        
+      
+    

+
+

+
 
Erts 7.2
 
     
Fixed Bugs and Malfunctions
-- 
cgit v1.2.3


From 37f58ad6bff2bf2bac4f3f20c2684e8cee66af03 Mon Sep 17 00:00:00 2001
From: Rickard Green 
Date: Tue, 15 Dec 2015 09:40:30 +0100
Subject: Light weight statistics of run queue lengths

- statistics(total_run_queue_lengths)
- statistics(run_queue_lengths)
- statistics(total_active_tasks)
- statistics(active_tasks)

Conflicts:
	erts/emulator/beam/erl_process.c
---
 erts/doc/src/erlang.xml | 111 ++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 99 insertions(+), 12 deletions(-)

(limited to 'erts/doc')

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index c37ed3bea5..64eebec936 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -5684,8 +5684,31 @@ true
Dest, Msg, []).

 + + Information about active processes and ports. + +

+ Returns a list where each element represents the amount + of active processes and ports on each run queue and its + associated scheduler. That is, the number of processes and + ports that are ready to run, or are currently running. The + element location in the list corresponds to the scheduler + and its run queue. The first element corresponds to scheduler + number 1 and so on. The information is not gathered + atomically. That is, the result is not necessarily a + consistent snapshot of the state, but instead quite + efficiently gathered. See also, + statistics(total_active_tasks), + statistics(run_queue_lengths), and + statistics(total_run_queue_lengths). +

+ + + + + Information about context switches.

Returns the total number of context switches since the @@ -5694,7 +5717,7 @@ true - + Information about exact reductions. @@ -5708,7 +5731,7 @@ true - + Information about garbage collection.

Returns information about garbage collection, for example:

@@ -5720,7 +5743,7 @@ true - + Information about I/O.

Returns Input, @@ -5731,7 +5754,7 @@ true - + Information about reductions. @@ -5749,16 +5772,43 @@ true - - Information about the run-queue. - -

Returns the total length of run-queues, that is, the number - of processes that are ready to run on all available run-queues.

+ + Information about the run-queues. + +

+ Returns the total length of the run-queues. That is, the number + of processes and ports that are ready to run on all available + run-queues. The information is gathered atomically. That + is, the result is a consistent snapshot of the state, but + this operation is much more expensive compared to + statistics(total_run_queue_lengths). + This especially when a large amount of schedulers is used. +

- + + Information about the run-queue lengths. + +

+ Returns a list where each element represents the amount + of processes and ports ready to run for each run queue. The + element location in the list corresponds to the run queue + of a scheduler. The first element corresponds to the run + queue of scheduler number 1 and so on. The information is + not gathered atomically. That is, the result is + not necessarily a consistent snapshot of the state, but + instead quite efficiently gathered. See also, + statistics(total_run_queue_lengths), + statistics(active_tasks), and + statistics(total_active_tasks). +

+ + + + + Information about runtime.

Returns information about runtime, in milliseconds.

@@ -5773,7 +5823,7 @@ true - + Information about each schedulers work time. @@ -5844,7 +5894,44 @@ ok - + + Information about active processes and ports. + +

+ Returns the total amount of active processes and ports in + the system. That is, the number of processes and ports that + are ready to run, or are currently running. The information + is not gathered atomically. That is, the result + is not necessarily a consistent snapshot of the state, but + instead quite efficiently gathered. See also, + statistics(active_tasks), + statistics(run_queue_lengths), and + statistics(total_run_queue_lengths). +

+ + + + + + Information about the run-queue lengths. + +

+ Returns the total length of the run-queues. That is, the number + of processes and ports that are ready to run on all available + run-queues. The information is not gathered atomically. + That is, the result is not necessarily a consistent snapshot of + the state, but much more efficiently gathered compared to + statistics(run_queue). + See also, + statistics(run_queue_lengths), + statistics(total_active_tasks), and + statistics(active_tasks). +

+ + + + + Information about wall clock.

Returns information about wall clock. wall_clock can -- cgit v1.2.3 From f5c9dd660f3f098ba1e2a4110be594013a6dff11 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Thu, 14 Jan 2016 12:07:39 +0100 Subject: Add documentation of '-path' flag to 'erl' This flag replaces the path specified in the boot script. It has always existed, but was earlier only documented in SASL (script). --- erts/doc/src/erl.xml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml index ec4a0dee05..e8621fecc3 100644 --- a/erts/doc/src/erl.xml +++ b/erts/doc/src/erl.xml @@ -382,6 +382,11 @@ similar to . See code(3).

+ + +

Replaces the path specified in the boot script. See + script(4).

+

Starts Erlang with a remote shell connected to .

-- cgit v1.2.3 From 43a7421c36d3feddb238b92426f938f11ef91174 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Thu, 14 Jan 2016 16:10:38 +0100 Subject: erts: Correct faulty doc for erlang:trace/3 The entire MFA tuple is replaced with 0, not just Arity. --- erts/doc/src/erlang.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index c37ed3bea5..20184bd7f3 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -8182,14 +8182,14 @@ timestamp() ->

When Pid is scheduled to run. The process runs in function {M, F, Arity}. On some rare occasions, the current function cannot be determined, - then the last element Arity is 0.

+ then the last element is 0.

 {trace, Pid, out, {M, F, Arity} | 0}

When Pid is scheduled out. The process was running in function {M, F, Arity}. On some rare occasions, the current function cannot be determined, then the last - element Arity is 0.

+ element is 0.

 {trace, Pid, gc_start, Info} -- cgit v1.2.3 From 34e02fed50bbaa2af7b1828968b6ec02a54e98c8 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 20 Jan 2016 09:54:00 +0100 Subject: erts: Improve the documentation of the abstract format --- erts/doc/src/absform.xml | 240 ++++++++++++++++++++++++++--------------------- 1 file changed, 131 insertions(+), 109 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index 1c0c3e1319..3f47b3061b 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -4,7 +4,7 @@
- 20012015 + 20012016 Ericsson AB. All Rights Reserved. @@ -80,12 +80,15 @@ Rep(F) = {attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}. If F is an attribute -export_type([Type_1/A_1, ..., Type_k/A_k]), then Rep(F) = {attribute,LINE,export_type,[{Type_1,A_1}, ..., {Type_k,A_k}]}. + If F is an attribute -optional_callbacks([Fun_1/A_1, ..., Fun_k/A_k]), then + Rep(F) = {attribute,LINE,optional_callbacks,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}. If F is an attribute -compile(Options), then Rep(F) = {attribute,LINE,compile,Options}. If F is an attribute -file(File,Line), then Rep(F) = {attribute,LINE,file,{File,Line}}. If F is a record declaration - -record(Name,{V_1, ..., V_k}), then Rep(F) = + -record(Name,{V_1, ..., V_k}), + where each V_i is a record field, then Rep(F) = {attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}. For Rep(V), see below. If F is a type declaration @@ -173,12 +176,12 @@
Patterns -

If Ps is a sequence of patterns P_1, ..., P_k, then +

If Ps is a sequence of patterns P_1, ..., P_k, then Rep(Ps) = [Rep(P_1), ..., Rep(P_k)]. Such sequences occur as the list of arguments to a function or fun.

Individual patterns are represented as follows:

- If P is an atomic literal L, then Rep(P) = Rep(L). + If P is an atomic literal L, then Rep(P) = Rep(L). If P is a compound pattern P_1 = P_2, then Rep(P) = {match,LINE,Rep(P_1),Rep(P_2)}. If P is a variable pattern V, then @@ -211,6 +214,10 @@ {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}. If P is #Name.Field, then Rep(P) = {record_index,LINE,Name,Rep(Field)}. + If P is a map pattern #{A_1, ..., A_k}, where each + A_i is an association P_i_1 := P_i_2, then Rep(P) = + {map,LINE,[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see + below. If P is ( P_0 ), then Rep(P) = Rep(P_0), that is, patterns cannot be distinguished from their bodies. @@ -221,11 +228,11 @@
Expressions -

A body B is a sequence of expressions E_1, ..., E_k, and - Rep(B) = [Rep(E_1), ..., Rep(E_k)].

+

A body B is a nonempty sequence of expressions E_1, ..., E_k, + and Rep(B) = [Rep(E_1), ..., Rep(E_k)].

An expression E is one of the following alternatives:

- If P is an atomic literal L, then Rep(P) = Rep(L). + If E is an atomic literal L, then Rep(E) = Rep(L). If E is P = E_0, then Rep(E) = {match,LINE,Rep(P),Rep(E_0)}. If E is a variable V, then Rep(E) = {var,LINE,A}, @@ -256,14 +263,16 @@ Rep(E) = {record_index,LINE,Name,Rep(Field)}. If E is E_0#Name.Field, then Rep(E) = {record_field,LINE,Rep(E_0),Name,Rep(Field)}. - If E is #{W_1, ..., W_k} where each - W_i is a map assoc or exact field, then Rep(E) = - {map,LINE,[Rep(W_1), ..., Rep(W_k)]}. For Rep(W), see + If E is a map creation #{A_1, ..., A_k}, + where each A_i is an association E_i_1 => E_i_2 + or E_i_1 := E_i_2, then Rep(E) = + {map,LINE,[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see below. - If E is E_0#{W_1, ..., W_k} where - W_i is a map assoc or exact field, then Rep(E) = - {map,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}. - For Rep(W), see below. + If E is a map update E_0#{A_1, ..., A_k}, + where each A_i is an association E_i_1 => E_i_2 + or E_i_1 := E_i_2, then Rep(E) = + {map,LINE,Rep(E_0),[Rep(A_1), ..., Rep(A_k)]}. + For Rep(A), see below. If E is catch E_0, then Rep(E) = {'catch',LINE,Rep(E_0)}. If E is E_0(E_1, ..., E_k), then @@ -271,15 +280,15 @@ If E is E_m:E_0(E_1, ..., E_k), then Rep(E) = {call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}. - If E is a list comprehension [E_0 || W_1, ..., W_k], - where each W_i is a generator or a filter, then Rep(E) = - {lc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}. For Rep(W), see + If E is a list comprehension [E_0 || Q_1, ..., Q_k], + where each Q_i is a qualifier, then Rep(E) = + {lc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}. For Rep(Q), see below. If E is a binary comprehension - <<E_0 || W_1, ..., W_k>>, - where each W_i is a generator or a filter, then - Rep(E) = {bc,LINE,Rep(E_0),[Rep(W_1), ..., Rep(W_k)]}. - For Rep(W), see below. + <<E_0 || Q_1, ..., Q_k>>, + where each Q_i is a qualifier, then + Rep(E) = {bc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}. + For Rep(Q), see below. If E is begin B end, where B is a body, then Rep(E) = {block,LINE,Rep(B)}. If E is if Ic_1 ; ... ; Ic_k end, @@ -311,7 +320,7 @@ {'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],Rep(A)}. If E is try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end, where B and A are a bodies, - each Cc_i is a case clause and + each Cc_i is a case clause, and each Tc_j is a catch clause then Rep(E) = {'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],Rep(A)}. @@ -328,10 +337,10 @@ {'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}. (Before the R15 release: Rep(E) = {'fun',LINE,{function,Module,Name,Arity}}.) - If E is fun Fc_1 ; ... ; Fc_k end + If E is fun Fc_1 ; ... ; Fc_k end, where each Fc_i is a function clause then Rep(E) = {'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}. - If E is fun Name Fc_1 ; ... ; Name Fc_k end + If E is fun Name Fc_1 ; ... ; Name Fc_k end, where Name is a variable and each Fc_i is a function clause then Rep(E) = {named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}. @@ -342,46 +351,43 @@
- Generators and Filters -

When W is a generator or a filter (in the body of a list or - binary comprehension), then:

+ Qualifiers +

A qualifier Q is one of the following alternatives:

- If W is a generator P <- E, where P is + If Q is a generator P <- E, where P is a pattern and E is an expression, then - Rep(W) = {generate,LINE,Rep(P),Rep(E)}. - If W is a generator P <= E, where P is + Rep(Q) = {generate,LINE,Rep(P),Rep(E)}. + If Q is a generator P <= E, where P is a pattern and E is an expression, then - Rep(W) = {b_generate,LINE,Rep(P),Rep(E)}. - If W is a filter E, which is an expression, then - Rep(W) = Rep(E). + Rep(Q) = {b_generate,LINE,Rep(P),Rep(E)}. + If Q is a filter E, where E is an expression, then + Rep(Q) = Rep(E).
Binary Element Type Specifiers

A type specifier list TSL for a binary element is a sequence of type - specifiers TS_1 - ... - TS_k. + specifiers TS_1 - ... - TS_k, and Rep(TSL) = [Rep(TS_1), ..., Rep(TS_k)].

-

When TS is a type specifier for a binary element, then:

- If TS is an atom A, then Rep(TS) = A. - If TS is a couple A:Value where A is an atom - and Value is an integer, then Rep(TS) = - {A,Value}. + If TS is a type specifier A, where A is an atom, + then Rep(TS) = A. + If TS is a type specifier A:Value, + where A is an atom and Value is an integer, + then Rep(TS) = {A,Value}.
- Map Assoc and Exact Fields -

When W is an assoc or exact field (in the body of a map), then:

+ Associations +

An association A is one of the following alternatives:

- If W is an assoc field K => V, where - K and V are both expressions, - then Rep(W) = {map_field_assoc,LINE,Rep(K),Rep(V)}. + If A is an association K => V, + then Rep(A) = {map_field_assoc,LINE,Rep(K),Rep(V)}. - If W is an exact field K := V, where - K and V are both expressions, - then Rep(W) = {map_field_exact,LINE,Rep(K),Rep(V)}. + If A is an association K := V, + then Rep(A) = {map_field_exact,LINE,Rep(K),Rep(V)}.
@@ -393,37 +399,37 @@ and catch clauses.

A clause C is one of the following alternatives:

- If C is a function clause ( Ps ) -> B + If C is a function clause ( Ps ) -> B, where Ps is a pattern sequence and B is a body, then Rep(C) = {clause,LINE,Rep(Ps),[],Rep(B)}. - If C is a function clause ( Ps ) when Gs -> B + If C is a function clause ( Ps ) when Gs -> B, where Ps is a pattern sequence, Gs is a guard sequence and B is a body, then Rep(C) = {clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}. - If C is an if clause Gs -> B + If C is an if clause Gs -> B, where Gs is a guard sequence and B is a body, then Rep(C) = {clause,LINE,[],Rep(Gs),Rep(B)}. - If C is a case clause P -> B + If C is a case clause P -> B, where P is a pattern and B is a body, then Rep(C) = {clause,LINE,[Rep(P)],[],Rep(B)}. - If C is a case clause P when Gs -> B + If C is a case clause P when Gs -> B, where P is a pattern, Gs is a guard sequence and B is a body, then Rep(C) = {clause,LINE,[Rep(P)],Rep(Gs),Rep(B)}. - If C is a catch clause P -> B + If C is a catch clause P -> B, where P is a pattern and B is a body, then Rep(C) = {clause,LINE,[Rep({throw,P,_})],[],Rep(B)}. - If C is a catch clause X : P -> B + If C is a catch clause X : P -> B, where X is an atomic literal or a variable pattern, - P is a pattern and B is a body, then + P is a pattern, and B is a body, then Rep(C) = {clause,LINE,[Rep({X,P,_})],[],Rep(B)}. - If C is a catch clause P when Gs -> B - where P is a pattern, Gs is a guard sequence + If C is a catch clause P when Gs -> B, + where P is a pattern, Gs is a guard sequence, and B is a body, then Rep(C) = {clause,LINE,[Rep({throw,P,_})],Rep(Gs),Rep(B)}. - If C is a catch clause X : P when Gs -> B + If C is a catch clause X : P when Gs -> B, where X is an atomic literal or a variable pattern, - P is a pattern, Gs is a guard sequence + P is a pattern, Gs is a guard sequence, and B is a body, then Rep(C) = {clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}. @@ -439,7 +445,7 @@ [Rep(Gt_1), ..., Rep(Gt_k)].

A guard test Gt is one of the following alternatives:

- If Gt is an atomic literal L, then Rep(Gt) = Rep(L). + If Gt is an atomic literal L, then Rep(Gt) = Rep(L). If Gt is a variable pattern V, then Rep(Gt) = {var,LINE,A}, where A is an atom with a printname consisting of the same characters as V. @@ -467,15 +473,21 @@ Rep(Gt) = {record_index,LINE,Name,Rep(Field)}. If Gt is Gt_0#Name.Field, then Rep(Gt) = {record_field,LINE,Rep(Gt_0),Name,Rep(Field)}. + If Gt is a map creation #{A_1, ..., A_k}, + where each A_i is an association Gt_i_1 => Gt_i_2 + or Gt_i_1 := Gt_i_2, then Rep(Gt) = + {map,LINE,[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see + above. + If Gt is a map update Gt_0#{A_1, ..., A_k}, where each + A_i is an association Gt_i_1 => Gt_i_2 + or Gt_i_1 := Gt_i_2, then Rep(Gt) = + {map,LINE,Rep(Gt_0),[Rep(A_1), ..., Rep(A_k)]}. + For Rep(A), see above. If Gt is A(Gt_1, ..., Gt_k), where A is an atom, then Rep(Gt) = {call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}. If Gt is A_m:A(Gt_1, ..., Gt_k), where A_m is the atom erlang and A is an atom or an operator, then Rep(Gt) = {call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}. - If Gt is {A_m,A}(Gt_1, ..., Gt_k), where A_m is - the atom erlang and A is an atom or an operator, then - Rep(Gt) = {call,LINE,Rep({A_m,A}),[Rep(Gt_1), ..., Rep(Gt_k)]}. - If Gt is ( Gt_0 ), then Rep(Gt) = Rep(Gt_0), that is, parenthesized guard tests cannot be distinguished from their bodies. @@ -487,21 +499,20 @@
Types - If T is an annotated type Anno :: Type, - where Anno is a variable and - Type is a type, then Rep(T) = - {ann_type,LINE,[Rep(Anno),Rep(Type)]}. + If T is an annotated type A :: T_0, + where A is a variable, then Rep(T) = + {ann_type,LINE,[Rep(A),Rep(T_0)]}. If T is an atom or integer literal L, then Rep(T) = Rep(L). - If T is L Op R, - where Op is a binary operator and L and R - are types (this is an occurrence of an expression that can be - evaluated to an integer at compile time), then - Rep(T) = {op,LINE,Op,Rep(L),Rep(R)}. - If T is Op A, where Op is a - unary operator and A is a type (this is an occurrence of + If T is an operator type T_1 Op T_2, + where Op is a binary operator (this is an occurrence of + an expression that can be evaluated to an integer at compile + time), then + Rep(T) = {op,LINE,Op,Rep(T_1),Rep(T_2)}. + If T is an operator type Op T_0, where Op is a + unary operator (this is an occurrence of an expression that can be evaluated to an integer at compile time), - then Rep(T) = {op,LINE,Op,Rep(A)}. + then Rep(T) = {op,LINE,Op,Rep(T_0)}. If T is a bitstring type <<_:M,_:_*N>>, where M and N are singleton integer types, then Rep(T) = {type,LINE,binary,[Rep(M),Rep(N)]}. @@ -509,53 +520,44 @@ {type,Line,nil,[]}. If T is a fun type fun(), then Rep(T) = {type,LINE,'fun',[]}. - If T is a fun type fun((...) -> B), - where B is a type, then - Rep(T) = {type,LINE,'fun',[{type,LINE,any},Rep(B)]}. + If T is a fun type fun((...) -> T_0), then + Rep(T) = {type,LINE,'fun',[{type,LINE,any},Rep(T_0)]}. If T is a fun type fun(Ft), where Ft is a function type, - then Rep(T) = Rep(Ft). + then Rep(T) = Rep(Ft). For Rep(Ft), see below. If T is an integer range type L .. H, where L and H are singleton integer types, then Rep(T) = {type,LINE,range,[Rep(L),Rep(H)]}. If T is a map type map(), then Rep(T) = {type,LINE,map,any}. - If T is a map type #{P_1, ..., P_k}, where each - P_i is a map pair type, then Rep(T) = - {type,LINE,map,[Rep(P_1), ..., Rep(P_k)]}. - If T is a map pair type K => V, where - K and V are types, then Rep(T) = - {type,LINE,map_field_assoc,[Rep(K),Rep(V)]}. - If T is a predefined (or built-in) type N(A_1, ..., A_k), - where each A_i is a type, then Rep(T) = - {type,LINE,N,[Rep(A_1), ..., Rep(A_k)]}. + If T is a map type #{A_1, ..., A_k}, where each + A_i is an association type, then Rep(T) = + {type,LINE,map,[Rep(A_1), ..., Rep(A_k)]}. + For Rep(A), see below. + If T is a predefined (or built-in) type N(T_1, ..., T_k), + then Rep(T) = + {type,LINE,N,[Rep(T_1), ..., Rep(T_k)]}. If T is a record type #Name{F_1, ..., F_k}, where each F_i is a record field type, then Rep(T) = {type,LINE,record,[Rep(Name),Rep(F_1), ..., Rep(F_k)]}. - - If T is a record field type Name :: Type, - where Type is a type, then Rep(T) = - {type,LINE,field_type,[Rep(Name),Rep(Type)]}. - If T is a remote type M:N(A_1, ..., A_k), where - each A_i is a type, then Rep(T) = - {remote_type,LINE,[Rep(M),Rep(N),[Rep(A_1), ..., Rep(A_k)]]}. + For Rep(F), see below. + If T is a remote type M:N(T_1, ..., T_k), then Rep(T) = + {remote_type,LINE,[Rep(M),Rep(N),[Rep(T_1), ..., Rep(T_k)]]}. If T is a tuple type tuple(), then Rep(T) = {type,LINE,tuple,any}. - If T is a tuple type {A_1, ..., A_k}, where - each A_i is a type, then Rep(T) = - {type,LINE,tuple,[Rep(A_1), ..., Rep(A_k)]}. - If T is a type union T_1 | ... | T_k, - where each T_i is a type, then Rep(T) = + If T is a tuple type {T_1, ..., T_k}, then Rep(T) = + {type,LINE,tuple,[Rep(T_1), ..., Rep(T_k)]}. + If T is a type union T_1 | ... | T_k, then Rep(T) = {type,LINE,union,[Rep(T_1), ..., Rep(T_k)]}. If T is a type variable V, then Rep(T) = {var,LINE,A}, where A is an atom with a printname consisting of the same characters as V. A type variable is any variable except underscore (_). - If T is a user-defined type N(A_1, ..., A_k), - where each A_i is a type, then Rep(T) = - {user_type,LINE,N,[Rep(A_1), ..., Rep(A_k)]}. + If T is a user-defined type N(T_1, ..., T_k), + then Rep(T) = + {user_type,LINE,N,[Rep(T_1), ..., Rep(T_k)]}. If T is ( T_0 ), then Rep(T) = Rep(T_0), that is, parenthesized types cannot be distinguished from their bodies. @@ -563,15 +565,17 @@
Function Types +

A function type Ft is one of the following alternatives:

If Ft is a constrained function type Ft_1 when Fc, where Ft_1 is a function type and Fc is a function constraint, then Rep(T) = - {type,LINE,bounded_fun,[Rep(Ft_1),Rep(Fc)]}. - If Ft is a function type (A_1, ..., A_n) -> B, - where each A_i and B are types, then - Rep(Ft) = {type,LINE,'fun',[{type,LINE,product,[Rep(A_1), - ..., Rep(A_n)]},Rep(B)]}. + {type,LINE,bounded_fun,[Rep(Ft_1),Rep(Fc)]}. + For Rep(Fc), see below. + If Ft is a function type (T_1, ..., T_n) -> T_0, + where each T_i is a type, then + Rep(Ft) = {type,LINE,'fun',[{type,LINE,product,[Rep(T_1), + ..., Rep(T_n)]},Rep(T_0)]}.
@@ -587,6 +591,24 @@
+ +
+ Association Types + + If A is an association type K => V, where + K and V are types, then Rep(A) = + {type,LINE,map_field_assoc,[Rep(K),Rep(V)]}. + +
+ +
+ Record Field Types + + If F is a record field type Name :: Type, + where Type is a type, then Rep(F) = + {type,LINE,field_type,[Rep(Name),Rep(Type)]}. + +
-- cgit v1.2.3 From 6e2d941bf278191c11f6d1cebdfab5e51419d734 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Wed, 20 Jan 2016 09:55:21 +0100 Subject: erts: Improve readability of The Abstract Format More verbose, but hopefully more readable than before. --- erts/doc/src/absform.xml | 420 +++++++++++++++++++++++++---------------------- 1 file changed, 228 insertions(+), 192 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml index 3f47b3061b..ccdecf44ec 100644 --- a/erts/doc/src/absform.xml +++ b/erts/doc/src/absform.xml @@ -68,34 +68,29 @@ If D is a module declaration consisting of the forms F_1, ..., F_k, then Rep(D) = [Rep(F_1), ..., Rep(F_k)]. - If F is an attribute -module(Mod), then - Rep(F) = {attribute,LINE,module,Mod}. If F is an attribute -behavior(Behavior), then Rep(F) = {attribute,LINE,behavior,Behavior}. If F is an attribute -behaviour(Behaviour), then Rep(F) = {attribute,LINE,behaviour,Behaviour}. + If F is an attribute -compile(Options), then + Rep(F) = {attribute,LINE,compile,Options}. If F is an attribute -export([Fun_1/A_1, ..., Fun_k/A_k]), then Rep(F) = {attribute,LINE,export,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}. - If F is an attribute -import(Mod,[Fun_1/A_1, ..., Fun_k/A_k]), then - Rep(F) = {attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}. If F is an attribute -export_type([Type_1/A_1, ..., Type_k/A_k]), then Rep(F) = {attribute,LINE,export_type,[{Type_1,A_1}, ..., {Type_k,A_k}]}. + If F is an attribute -import(Mod,[Fun_1/A_1, ..., Fun_k/A_k]), then + Rep(F) = {attribute,LINE,import,{Mod,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}}. + If F is an attribute -module(Mod), then + Rep(F) = {attribute,LINE,module,Mod}. If F is an attribute -optional_callbacks([Fun_1/A_1, ..., Fun_k/A_k]), then Rep(F) = {attribute,LINE,optional_callbacks,[{Fun_1,A_1}, ..., {Fun_k,A_k}]}. - If F is an attribute -compile(Options), then - Rep(F) = {attribute,LINE,compile,Options}. If F is an attribute -file(File,Line), then Rep(F) = {attribute,LINE,file,{File,Line}}. - If F is a record declaration - -record(Name,{V_1, ..., V_k}), - where each V_i is a record field, then Rep(F) = - {attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}. - For Rep(V), see below. - If F is a type declaration - -Type Name(V_1, ..., V_k) :: T, where - Type is either the atom type or the atom opaque, - each V_i is a variable, and T is a type, then Rep(F) = - {attribute,LINE,Type,{Name,Rep(T),[Rep(V_1), ..., Rep(V_k)]}}. + If F is a function declaration + Name Fc_1 ; ... ; Name Fc_k, + where each Fc_i is a function clause with a + pattern sequence of the same length Arity, then + Rep(F) = {function,LINE,Name,Arity,[Rep(Fc_1), ...,Rep(Fc_k)]}. If F is a function specification -Spec Name Ft_1; ...; Ft_k, @@ -112,15 +107,20 @@ Arity, then Rep(F) = {attribute,Line,spec,{{Mod,Name,Arity},[Rep(Ft_1), ..., Rep(Ft_k)]}}. + If F is a record declaration + -record(Name,{V_1, ..., V_k}), + where each V_i is a record field, then Rep(F) = + {attribute,LINE,record,{Name,[Rep(V_1), ..., Rep(V_k)]}}. + For Rep(V), see below. + If F is a type declaration + -Type Name(V_1, ..., V_k) :: T, where + Type is either the atom type or the atom opaque, + each V_i is a variable, and T is a type, then Rep(F) = + {attribute,LINE,Type,{Name,Rep(T),[Rep(V_1), ..., Rep(V_k)]}}. + If F is a wild attribute -A(T), then Rep(F) = {attribute,LINE,A,T}.

- If F is a function declaration - Name Fc_1 ; ... ; Name Fc_k, - where each Fc_i is a function clause with a - pattern sequence of the same length Arity, then - Rep(F) = {function,LINE,Name,Arity,[Rep(Fc_1), ...,Rep(Fc_k)]}. -
@@ -160,15 +160,15 @@

There are five kinds of atomic literals, which are represented in the same way in patterns, expressions and guards:

- If L is an integer or character literal, then - Rep(L) = {integer,LINE,L}. + If L is an atom literal, then + Rep(L) = {atom,LINE,L}. If L is a float literal, then Rep(L) = {float,LINE,L}. + If L is an integer or character literal, then + Rep(L) = {integer,LINE,L}. If L is a string literal consisting of the characters C_1, ..., C_k, then Rep(L) = {string,LINE,[C_1, ..., C_k]}. - If L is an atom literal, then - Rep(L) = {atom,LINE,L}.

Note that negative integer and float literals do not occur as such; they are parsed as an application of the unary negation operator.

@@ -182,45 +182,53 @@

Individual patterns are represented as follows:

If P is an atomic literal L, then Rep(P) = Rep(L). + If P is a binary pattern + <<P_1:Size_1/TSL_1, ..., P_k:Size_k/TSL_k>>, where each + Size_i is an expression that can be evaluated to an integer + and each TSL_i is a type specificer list, then + Rep(P) = {bin,LINE,[{bin_element,LINE,Rep(P_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(P_k),Rep(Size_k),Rep(TSL_k)}]}. + For Rep(TSL), see below. + An omitted Size_i is represented by default. + An omitted TSL_i is represented by default. If P is a compound pattern P_1 = P_2, then Rep(P) = {match,LINE,Rep(P_1),Rep(P_2)}. - If P is a variable pattern V, then - Rep(P) = {var,LINE,A}, - where A is an atom with a printname consisting of the same characters as - V. - If P is a universal pattern _, then - Rep(P) = {var,LINE,'_'}. - If P is a tuple pattern {P_1, ..., P_k}, then - Rep(P) = {tuple,LINE,[Rep(P_1), ..., Rep(P_k)]}. - If P is a nil pattern [], then - Rep(P) = {nil,LINE}. If P is a cons pattern [P_h | P_t], then Rep(P) = {cons,LINE,Rep(P_h),Rep(P_t)}. - If E is a binary pattern <<P_1:Size_1/TSL_1, ..., P_k:Size_k/TSL_k>>, then - Rep(E) = {bin,LINE,[{bin_element,LINE,Rep(P_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(P_k),Rep(Size_k),Rep(TSL_k)}]}. - For Rep(TSL), see below. - An omitted Size is represented by default. An omitted TSL - (type specifier list) is represented by default. - If P is P_1 Op P_2, where Op is a binary operator (this - is either an occurrence of ++ applied to a literal string or character - list, or an occurrence of an expression that can be evaluated to a number - at compile time), - then Rep(P) = {op,LINE,Op,Rep(P_1),Rep(P_2)}. - If P is Op P_0, where Op is a unary operator (this is an - occurrence of an expression that can be evaluated to a number at compile - time), then Rep(P) = {op,LINE,Op,Rep(P_0)}. - If P is a record pattern #Name{Field_1=P_1, ..., Field_k=P_k}, - then Rep(P) = - {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}. - If P is #Name.Field, then - Rep(P) = {record_index,LINE,Name,Rep(Field)}. If P is a map pattern #{A_1, ..., A_k}, where each A_i is an association P_i_1 := P_i_2, then Rep(P) = {map,LINE,[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see below. - If P is ( P_0 ), then + If P is a nil pattern [], then + Rep(P) = {nil,LINE}. + If P is an operator pattern P_1 Op P_2, + where Op is a binary operator (this is either an occurrence + of ++ applied to a literal string or character + list, or an occurrence of an expression that can be evaluated to a number + at compile time), + then Rep(P) = {op,LINE,Op,Rep(P_1),Rep(P_2)}. + If P is an operator pattern Op P_0, + where Op is a unary operator (this is an occurrence of + an expression that can be evaluated to a number at compile + time), then Rep(P) = {op,LINE,Op,Rep(P_0)}. + If P is a parenthesized pattern ( P_0 ), then Rep(P) = Rep(P_0), - that is, patterns cannot be distinguished from their bodies. + that is, parenthesized patterns cannot be distinguished from their + bodies. + If P is a record field index pattern #Name.Field, + where Field is an atom, then + Rep(P) = {record_index,LINE,Name,Rep(Field)}. + If P is a record pattern + #Name{Field_1=P_1, ..., Field_k=P_k}, + where each Field_i is an atom or _, then Rep(P) = + {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(P_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(P_k)}]}. + If P is a tuple pattern {P_1, ..., P_k}, then + Rep(P) = {tuple,LINE,[Rep(P_1), ..., Rep(P_k)]}. + If P is a universal pattern _, then + Rep(P) = {var,LINE,'_'}. + If P is a variable pattern V, then + Rep(P) = {var,LINE,A}, + where A is an atom with a printname consisting of the same characters as + V.

Note that every pattern has the same source form as some expression, and is represented the same way as the corresponding expression.

@@ -233,36 +241,58 @@

An expression E is one of the following alternatives:

If E is an atomic literal L, then Rep(E) = Rep(L). - If E is P = E_0, then - Rep(E) = {match,LINE,Rep(P),Rep(E_0)}. - If E is a variable V, then Rep(E) = {var,LINE,A}, - where A is an atom with a printname consisting of the same - characters as V. - If E is a tuple skeleton {E_1, ..., E_k}, then - Rep(E) = {tuple,LINE,[Rep(E_1), ..., Rep(E_k)]}. - If E is [], then - Rep(E) = {nil,LINE}. + If E is a binary comprehension + <<E_0 || Q_1, ..., Q_k>>, + where each Q_i is a qualifier, then + Rep(E) = {bc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}. + For Rep(Q), see below. + If E is a binary constructor <<E_1:Size_1/TSL_1, ..., E_k:Size_k/TSL_k>>, + where each Size_i is an expression and each + TSL_i is a type specificer list, then Rep(E) = + {bin,LINE,[{bin_element,LINE,Rep(E_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(E_k),Rep(Size_k),Rep(TSL_k)}]}. + For Rep(TSL), see below. + An omitted Size_i is represented by default. + An omitted TSL_i is represented by default. + If E is a block expression begin B end, + where B is a body, then + Rep(E) = {block,LINE,Rep(B)}. + If E is a case expression case E_0 of Cc_1 ; ... ; Cc_k end, + where E_0 is an expression and each Cc_i is a + case clause then Rep(E) = + {'case',LINE,Rep(E_0),[Rep(Cc_1), ..., Rep(Cc_k)]}. + If E is a catch expression catch E_0, then + Rep(E) = {'catch',LINE,Rep(E_0)}. If E is a cons skeleton [E_h | E_t], then Rep(E) = {cons,LINE,Rep(E_h),Rep(E_t)}. - If E is a binary constructor <<V_1:Size_1/TSL_1, ..., V_k:Size_k/TSL_k>>, then Rep(E) = - {bin,LINE,[{bin_element,LINE,Rep(V_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(V_k),Rep(Size_k),Rep(TSL_k)}]}. - For Rep(TSL), see below. - An omitted Size is represented by default. An omitted TSL - (type specifier list) is represented by default. - If E is E_1 Op E_2, where Op is a binary operator, - then Rep(E) = {op,LINE,Op,Rep(E_1),Rep(E_2)}. - If E is Op E_0, where Op is a unary operator, then - Rep(E) = {op,LINE,Op,Rep(E_0)}. - If E is #Name{Field_1=E_1, ..., Field_k=E_k}, + If E is a fun expression fun Name/Arity, then + Rep(E) = {'fun',LINE,{function,Name,Arity}}. + If E is a fun expression + fun Module:Name/Arity, then Rep(E) = + {'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}. + (Before the R15 release: Rep(E) = + {'fun',LINE,{function,Module,Name,Arity}}.) + If E is a fun expression fun Fc_1 ; ... ; Fc_k end, + where each Fc_i is a function clause then Rep(E) = + {'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}. + If E is a fun expression + fun Name Fc_1 ; ... ; Name Fc_k end, + where Name is a variable and each + Fc_i is a function clause then Rep(E) = + {named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}. + + If E is a function call E_0(E_1, ..., E_k), then + Rep(E) = {call,LINE,Rep(E_0),[Rep(E_1), ..., Rep(E_k)]}. + If E is a function call E_m:E_0(E_1, ..., E_k), then Rep(E) = - {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}. - If E is E_0#Name{Field_1=E_1, ..., Field_k=E_k}, then - Rep(E) = - {record,LINE,Rep(E_0),Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}. - If E is #Name.Field, then - Rep(E) = {record_index,LINE,Name,Rep(Field)}. - If E is E_0#Name.Field, then - Rep(E) = {record_field,LINE,Rep(E_0),Name,Rep(Field)}. + {call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}. + + If E is an if expression if Ic_1 ; ... ; Ic_k end, + where each Ic_i is an if clause then Rep(E) = + {'if',LINE,[Rep(Ic_1), ..., Rep(Ic_k)]}. + If E is a list comprehension [E_0 || Q_1, ..., Q_k], + where each Q_i is a qualifier, then Rep(E) = + {lc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}. For Rep(Q), see + below. If E is a map creation #{A_1, ..., A_k}, where each A_i is an association E_i_1 => E_i_2 or E_i_1 := E_i_2, then Rep(E) = @@ -273,95 +303,92 @@ or E_i_1 := E_i_2, then Rep(E) = {map,LINE,Rep(E_0),[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see below. - If E is catch E_0, then - Rep(E) = {'catch',LINE,Rep(E_0)}. - If E is E_0(E_1, ..., E_k), then - Rep(E) = {call,LINE,Rep(E_0),[Rep(E_1), ..., Rep(E_k)]}. - If E is E_m:E_0(E_1, ..., E_k), then Rep(E) = - {call,LINE,{remote,LINE,Rep(E_m),Rep(E_0)},[Rep(E_1), ..., Rep(E_k)]}. - - If E is a list comprehension [E_0 || Q_1, ..., Q_k], - where each Q_i is a qualifier, then Rep(E) = - {lc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}. For Rep(Q), see - below. - If E is a binary comprehension - <<E_0 || Q_1, ..., Q_k>>, - where each Q_i is a qualifier, then - Rep(E) = {bc,LINE,Rep(E_0),[Rep(Q_1), ..., Rep(Q_k)]}. - For Rep(Q), see below. - If E is begin B end, where B is a body, then - Rep(E) = {block,LINE,Rep(B)}. - If E is if Ic_1 ; ... ; Ic_k end, - where each Ic_i is an if clause then Rep(E) = - {'if',LINE,[Rep(Ic_1), ..., Rep(Ic_k)]}. - If E is case E_0 of Cc_1 ; ... ; Cc_k end, - where E_0 is an expression and each Cc_i is a - case clause then Rep(E) = - {'case',LINE,Rep(E_0),[Rep(Cc_1), ..., Rep(Cc_k)]}. - If E is try B catch Tc_1 ; ... ; Tc_k end, + If E is a match operator expression P = E_0, + where P is a pattern, then + Rep(E) = {match,LINE,Rep(P),Rep(E_0)}. + If E is nil, [], then + Rep(E) = {nil,LINE}. + If E is an operator expression E_1 Op E_2, + where Op is a binary operator other than the match + operator =, then + Rep(E) = {op,LINE,Op,Rep(E_1),Rep(E_2)}. + If E is an operator expression Op E_0, + where Op is a unary operator, then + Rep(E) = {op,LINE,Op,Rep(E_0)}. + If E is a parenthesized expression ( E_0 ), then + Rep(E) = Rep(E_0), that is, parenthesized + expressions cannot be distinguished from their bodies. + If E is a receive expression receive Cc_1 ; ... ; Cc_k end, + where each Cc_i is a case clause then Rep(E) = + {'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)]}. + If E is a receive expression + receive Cc_1 ; ... ; Cc_k after E_0 -> B_t end, + where each Cc_i is a case clause, + E_0 is an expression and B_t is a body, then Rep(E) = + {'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)],Rep(E_0),Rep(B_t)}. + If E is a record creation + #Name{Field_1=E_1, ..., Field_k=E_k}, + where each Field_i is an atom or _, then Rep(E) = + {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}. + If E is a record field access E_0#Name.Field, + where Field is an atom, then + Rep(E) = {record_field,LINE,Rep(E_0),Name,Rep(Field)}. + If E is a record field index #Name.Field, + where Field is an atom, then + Rep(E) = {record_index,LINE,Name,Rep(Field)}. + If E is a record update + E_0#Name{Field_1=E_1, ..., Field_k=E_k}, + where each Field_i is an atom, then Rep(E) = + {record,LINE,Rep(E_0),Name,[{record_field,LINE,Rep(Field_1),Rep(E_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(E_k)}]}. + If E is a tuple skeleton {E_1, ..., E_k}, then + Rep(E) = {tuple,LINE,[Rep(E_1), ..., Rep(E_k)]}. + If E is a try expression try B catch Tc_1 ; ... ; Tc_k end, where B is a body and each Tc_i is a catch clause then Rep(E) = {'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],[]}. - If E is try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n end, + If E is a try expression + try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n end, where B is a body, each Cc_i is a case clause and each Tc_j is a catch clause then Rep(E) = {'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],[]}. - If E is try B after A end, + If E is a try expression try B after A end, where B and A are bodies then Rep(E) = {'try',LINE,Rep(B),[],[],Rep(A)}. - If E is try B of Cc_1 ; ... ; Cc_k after A end, + If E is a try expression + try B of Cc_1 ; ... ; Cc_k after A end, where B and A are a bodies and each Cc_i is a case clause then Rep(E) = {'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[],Rep(A)}. - If E is try B catch Tc_1 ; ... ; Tc_k after A end, + If E is a try expression + try B catch Tc_1 ; ... ; Tc_k after A end, where B and A are bodies and each Tc_i is a catch clause then Rep(E) = {'try',LINE,Rep(B),[],[Rep(Tc_1), ..., Rep(Tc_k)],Rep(A)}. - If E is try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end, + If E is a try expression + try B of Cc_1 ; ... ; Cc_k catch Tc_1 ; ... ; Tc_n after A end, where B and A are a bodies, each Cc_i is a case clause, and each Tc_j is a catch clause then Rep(E) = {'try',LINE,Rep(B),[Rep(Cc_1), ..., Rep(Cc_k)],[Rep(Tc_1), ..., Rep(Tc_n)],Rep(A)}. - If E is receive Cc_1 ; ... ; Cc_k end, - where each Cc_i is a case clause then Rep(E) = - {'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)]}. - If E is receive Cc_1 ; ... ; Cc_k after E_0 -> B_t end, - where each Cc_i is a case clause, - E_0 is an expression and B_t is a body, then Rep(E) = - {'receive',LINE,[Rep(Cc_1), ..., Rep(Cc_k)],Rep(E_0),Rep(B_t)}. - If E is fun Name / Arity, then - Rep(E) = {'fun',LINE,{function,Name,Arity}}. - If E is fun Module:Name/Arity, then Rep(E) = - {'fun',LINE,{function,Rep(Module),Rep(Name),Rep(Arity)}}. - (Before the R15 release: Rep(E) = - {'fun',LINE,{function,Module,Name,Arity}}.) - If E is fun Fc_1 ; ... ; Fc_k end, - where each Fc_i is a function clause then Rep(E) = - {'fun',LINE,{clauses,[Rep(Fc_1), ..., Rep(Fc_k)]}}. - If E is fun Name Fc_1 ; ... ; Name Fc_k end, - where Name is a variable and each - Fc_i is a function clause then Rep(E) = - {named_fun,LINE,Name,[Rep(Fc_1), ..., Rep(Fc_k)]}. - - If E is ( E_0 ), then - Rep(E) = Rep(E_0), that is, parenthesized - expressions cannot be distinguished from their bodies. + If E is a variable V, then Rep(E) = {var,LINE,A}, + where A is an atom with a printname consisting of the same + characters as V.
Qualifiers

A qualifier Q is one of the following alternatives:

+ If Q is a filter E, where E is an expression, then + Rep(Q) = Rep(E). If Q is a generator P <- E, where P is a pattern and E is an expression, then Rep(Q) = {generate,LINE,Rep(P),Rep(E)}. If Q is a generator P <= E, where P is a pattern and E is an expression, then Rep(Q) = {b_generate,LINE,Rep(P),Rep(E)}. - If Q is a filter E, where E is an expression, then - Rep(Q) = Rep(E).
@@ -399,16 +426,6 @@ and catch clauses.

A clause C is one of the following alternatives:

- If C is a function clause ( Ps ) -> B, - where Ps is a pattern sequence and B is a body, then - Rep(C) = {clause,LINE,Rep(Ps),[],Rep(B)}. - If C is a function clause ( Ps ) when Gs -> B, - where Ps is a pattern sequence, - Gs is a guard sequence and B is a body, then - Rep(C) = {clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}. - If C is an if clause Gs -> B, - where Gs is a guard sequence and B is a body, then - Rep(C) = {clause,LINE,[],Rep(Gs),Rep(B)}. If C is a case clause P -> B, where P is a pattern and B is a body, then Rep(C) = {clause,LINE,[Rep(P)],[],Rep(B)}. @@ -432,6 +449,16 @@ P is a pattern, Gs is a guard sequence, and B is a body, then Rep(C) = {clause,LINE,[Rep({X,P,_})],Rep(Gs),Rep(B)}. + If C is a function clause ( Ps ) -> B, + where Ps is a pattern sequence and B is a body, then + Rep(C) = {clause,LINE,Rep(Ps),[],Rep(B)}. + If C is a function clause ( Ps ) when Gs -> B, + where Ps is a pattern sequence, + Gs is a guard sequence and B is a body, then + Rep(C) = {clause,LINE,Rep(Ps),Rep(Gs),Rep(B)}. + If C is an if clause Gs -> B, + where Gs is a guard sequence and B is a body, then + Rep(C) = {clause,LINE,[],Rep(Gs),Rep(B)}.
@@ -446,33 +473,23 @@

A guard test Gt is one of the following alternatives:

If Gt is an atomic literal L, then Rep(Gt) = Rep(L). - If Gt is a variable pattern V, then - Rep(Gt) = {var,LINE,A}, where A is an atom with - a printname consisting of the same characters as V. - If Gt is a tuple skeleton {Gt_1, ..., Gt_k}, then - Rep(Gt) = {tuple,LINE,[Rep(Gt_1), ..., Rep(Gt_k)]}. - If Gt is [], then Rep(Gt) = {nil,LINE}. - If Gt is a cons skeleton [Gt_h | Gt_t], then - Rep(Gt) = {cons,LINE,Rep(Gt_h),Rep(Gt_t)}. If Gt is a binary constructor - <<Gt_1:Size_1/TSL_1, ..., Gt_k:Size_k/TSL_k>>, then + <<Gt_1:Size_1/TSL_1, ..., Gt_k:Size_k/TSL_k>>, + where each Size_i is a guard test and each + TSL_i is a type specificer list, then Rep(Gt) = {bin,LINE,[{bin_element,LINE,Rep(Gt_1),Rep(Size_1),Rep(TSL_1)}, ..., {bin_element,LINE,Rep(Gt_k),Rep(Size_k),Rep(TSL_k)}]}. For Rep(TSL), see above. - An omitted Size is represented by default. - An omitted TSL (type specifier list) is represented - by default. - If Gt is Gt_1 Op Gt_2, where Op - is a binary operator, then Rep(Gt) = - {op,LINE,Op,Rep(Gt_1),Rep(Gt_2)}. - If Gt is Op Gt_0, where Op is a unary operator, then - Rep(Gt) = {op,LINE,Op,Rep(Gt_0)}. - If Gt is #Name{Field_1=Gt_1, ..., Field_k=Gt_k}, then - Rep(E) = - {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(Gt_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(Gt_k)}]}. - If Gt is #Name.Field, then - Rep(Gt) = {record_index,LINE,Name,Rep(Field)}. - If Gt is Gt_0#Name.Field, then - Rep(Gt) = {record_field,LINE,Rep(Gt_0),Name,Rep(Field)}. + An omitted Size_i is represented by default. + An omitted TSL_i is represented by default. + If Gt is a cons skeleton [Gt_h | Gt_t], then + Rep(Gt) = {cons,LINE,Rep(Gt_h),Rep(Gt_t)}. + If Gt is a function call A(Gt_1, ..., Gt_k), + where A is an atom, then Rep(Gt) = + {call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}. + If Gt is a function call A_m:A(Gt_1, ..., Gt_k), + where A_m is the atom erlang and A is + an atom or an operator, then Rep(Gt) = + {call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}. If Gt is a map creation #{A_1, ..., A_k}, where each A_i is an association Gt_i_1 => Gt_i_2 or Gt_i_1 := Gt_i_2, then Rep(Gt) = @@ -483,14 +500,33 @@ or Gt_i_1 := Gt_i_2, then Rep(Gt) = {map,LINE,Rep(Gt_0),[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see above. - If Gt is A(Gt_1, ..., Gt_k), where A is an atom, then - Rep(Gt) = {call,LINE,Rep(A),[Rep(Gt_1), ..., Rep(Gt_k)]}. - If Gt is A_m:A(Gt_1, ..., Gt_k), where A_m is - the atom erlang and A is an atom or an operator, then - Rep(Gt) = {call,LINE,{remote,LINE,Rep(A_m),Rep(A)},[Rep(Gt_1), ..., Rep(Gt_k)]}. - If Gt is ( Gt_0 ), then + If Gt is nil, [], + then Rep(Gt) = {nil,LINE}. + If Gt is an operator guard test Gt_1 Op Gt_2, + where Op is a binary operator other than the match + operator =, then + Rep(Gt) = {op,LINE,Op,Rep(Gt_1),Rep(Gt_2)}. + If Gt is an operator guard test Op Gt_0, + where Op is a unary operator, then + Rep(Gt) = {op,LINE,Op,Rep(Gt_0)}. + If Gt is a parenthesized guard test ( Gt_0 ), then Rep(Gt) = Rep(Gt_0), that is, parenthesized guard tests cannot be distinguished from their bodies. + If Gt is a record creation + #Name{Field_1=Gt_1, ..., Field_k=Gt_k}, + where each Field_i is an atom or _, then Rep(Gt) = + {record,LINE,Name,[{record_field,LINE,Rep(Field_1),Rep(Gt_1)}, ..., {record_field,LINE,Rep(Field_k),Rep(Gt_k)}]}. + If Gt is a record field access Gt_0#Name.Field, + where Field is an atom, then + Rep(Gt) = {record_field,LINE,Rep(Gt_0),Name,Rep(Field)}. + If Gt is a record field index #Name.Field, + where Field is an atom, then + Rep(Gt) = {record_index,LINE,Name,Rep(Field)}. + If Gt is a tuple skeleton {Gt_1, ..., Gt_k}, then + Rep(Gt) = {tuple,LINE,[Rep(Gt_1), ..., Rep(Gt_k)]}. + If Gt is a variable pattern V, then + Rep(Gt) = {var,LINE,A}, where A is an atom with + a printname consisting of the same characters as V.

Note that every guard test has the same source form as some expression, and is represented the same way as the corresponding expression.

@@ -504,15 +540,6 @@ {ann_type,LINE,[Rep(A),Rep(T_0)]}. If T is an atom or integer literal L, then Rep(T) = Rep(L). - If T is an operator type T_1 Op T_2, - where Op is a binary operator (this is an occurrence of - an expression that can be evaluated to an integer at compile - time), then - Rep(T) = {op,LINE,Op,Rep(T_1),Rep(T_2)}. - If T is an operator type Op T_0, where Op is a - unary operator (this is an occurrence of - an expression that can be evaluated to an integer at compile time), - then Rep(T) = {op,LINE,Op,Rep(T_0)}. If T is a bitstring type <<_:M,_:_*N>>, where M and N are singleton integer types, then Rep(T) = {type,LINE,binary,[Rep(M),Rep(N)]}. @@ -535,6 +562,18 @@ A_i is an association type, then Rep(T) = {type,LINE,map,[Rep(A_1), ..., Rep(A_k)]}. For Rep(A), see below. + If T is an operator type T_1 Op T_2, + where Op is a binary operator (this is an occurrence of + an expression that can be evaluated to an integer at compile + time), then + Rep(T) = {op,LINE,Op,Rep(T_1),Rep(T_2)}. + If T is an operator type Op T_0, where Op is a + unary operator (this is an occurrence of + an expression that can be evaluated to an integer at compile time), + then Rep(T) = {op,LINE,Op,Rep(T_0)}. + If T is ( T_0 ), then Rep(T) = Rep(T_0), + that is, parenthesized types cannot be distinguished from their + bodies. If T is a predefined (or built-in) type N(T_1, ..., T_k), then Rep(T) = {type,LINE,N,[Rep(T_1), ..., Rep(T_k)]}. @@ -558,9 +597,6 @@ If T is a user-defined type N(T_1, ..., T_k), then Rep(T) = {user_type,LINE,N,[Rep(T_1), ..., Rep(T_k)]}. - If T is ( T_0 ), then Rep(T) = Rep(T_0), - that is, parenthesized types cannot be distinguished from their - bodies.
-- cgit v1.2.3 From 858c6f7fa44f7b2dc363b359198d6522dd60e914 Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 5 Jan 2016 16:55:04 +0100 Subject: Introduce time warp safe trace timestamp formats New timestamp options for trace, sequential trace, and system profile: - monotonic_timestamp - strict_monotonic_timestamp --- erts/doc/src/erlang.xml | 64 +++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 60 insertions(+), 4 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 64eebec936..79d3f66ea8 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -7739,6 +7739,13 @@ ok inactive, and later active when the port callback returns.

+ monotonic_timestamp + +

Timestamps in profile messages will use + Erlang + monotonic time. The time-stamp (Ts) has the same + format and value as produced by erlang:monotonic_time().

+ runnable_procs

If a process is put into or removed from the run queue, a @@ -7759,6 +7766,25 @@ ok {profile, scheduler, Id, State, NoScheds, Ts}, is sent to ProfilerPid.

 + strict_monotonic_timestamp + +

Timestamps in profile messages will consisting of + Erlang + monotonic time and a monotonically increasing + integer. The time-stamp (Ts) has the same format and value + as produced by {erlang:monotonic_time(), + erlang:unique_integer([monotonic])}.

+ + timestamp + +

Timestamps in profile messages will include a + time-stamp (Ts) that has the same form as returned by + erlang:now(). This is also the default if no + timestamp flag is given. If cpu_timestamp has + been enabled via erlang:trace/3, this will also + effect the timestamp produced in profiling messages + when timestamp flag is enabled.

+

erlang:system_profile is considered experimental and its behavior can change in a future release.

@@ -8118,7 +8144,10 @@ timestamp() -> cpu_timestamp

A global trace flag for the Erlang node that makes all - trace time-stamps to be in CPU time, not wall clock time. + trace time-stamps using the timestamp flag to be + in CPU time, not wall clock time. That is, cpu_timestamp + will not be used if monotonic_timestamp, or + strict_monotonic_timestamp is enabled. Only allowed with PidSpec==all. If the host machine OS does not support high-resolution CPU time measurements, trace/3 exits with @@ -8126,6 +8155,26 @@ timestamp() -> not synchronize this value across cores, so be prepared that time might seem to go backwards when using this option.

 + monotonic_timestamp + +

Includes an + Erlang + monotonic time time-stamp in all trace messages. The + time-stamp (Ts) has the same format and value as produced by + erlang:monotonic_time(). This flag overrides + the cpu_timestamp flag.

+ + strict_monotonic_timestamp + +

Includes an timestamp consisting of + Erlang + monotonic time and a monotonically increasing + integer in all trace messages. The time-stamp (Ts) has the + same format and value as produced by + {erlang:monotonic_time(), + erlang:unique_integer([monotonic])}. This flag overrides + the cpu_timestamp flag.

+ arity

Used with the call trace flag. @@ -8172,9 +8221,16 @@ timestamp() -> in the following list. Pid is the process identifier of the traced process in which the traced event has occurred. The third tuple element is the message tag.

-

If flag timestamp is given, the first tuple - element is trace_ts instead, and the time-stamp - is added last in the message tuple.

+

If flag timestamp, strict_monotonic_timestamp, or + monotonic_timestamp is given, the first tuple + element is trace_ts instead, and the time-stamp + is added as an extra element last in the message tuple. If + multiple timestamp flags are passed, timestamp has + precedence over strict_monotonic_timestamp which + in turn has precedence over monotonic_timestamp. All + timestamp flags are remembered, so if two are passed + and the one with highest precedence later is disabled + the other one will become active.

{trace, Pid, 'receive', Msg} -- cgit v1.2.3 From 53dcd92be965d35ef53a27efda0597b2961921ba Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Wed, 20 Jan 2016 19:42:31 +0100 Subject: erts: Update docs for erlang:purge_module/1 --- erts/doc/src/erlang.xml | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 8ddbd95de5..72d08a03fe 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -4870,6 +4870,12 @@ os_prompt% code(3)) and is not to be used elsewhere.

+ +

As from ERTS 8.0 (OTP 19), any lingering processes + that still execute the old code will be killed by this function. + In earlier versions, such incorrect use could cause much + more fatal failures, like emulator crash.

+

Failure: badarg if there is no old code for Module.

-- cgit v1.2.3 From 3f33428db9aea0d767295322c4e882a5c6bbf7db Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 19 Jan 2016 17:05:55 +0100 Subject: Introduce time management in native APIs --- erts/doc/src/erl_driver.xml | 112 ++++++++++++++++++++++++++++++++++++++++++++ erts/doc/src/erl_nif.xml | 112 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 224 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index e717fc0c4e..e338e95938 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -347,6 +347,16 @@ the driver does not handle sizes that overflow an int all will work as before.

 + Time Measurement +

Support for time measurement in drivers: + + ErlDrvTime + ErlDrvTimeUnit + erl_drv_monotonic_time() + erl_drv_time_offset() + erl_drv_convert_time_unit() +

+
@@ -860,6 +870,24 @@ typedef struct ErlIOVec { erl_drv_tsd_get().

+ ErlDrvTime + +

A signed 64-bit integer type for representation of time.

+ + ErlDrvTimeUnit + +

An enumeration of time units supported by the driver API:

+ + ERL_DRV_SEC +

Seconds

 + ERL_DRV_MSEC +

Milliseconds

 + ERL_DRV_USEC +

Microseconds

 + ERL_DRV_NSEC +

Nanoseconds

 + +
@@ -1023,6 +1051,10 @@ typedef struct ErlIOVec { Read a system timestamp +

This function is deprecated! Do not use it! + Use the documented + time measurement functionality + instead.

This function reads a timestamp into the memory pointed to by the parameter now. See the description of ErlDrvNowData for specification of its fields.

@@ -2997,6 +3029,86 @@ ERL_DRV_MAP int sz + + ErlDrvTimeerl_drv_monotonic_time(ErlDrvTimeUnit time_unit) + Get Erlang Monotonic Time + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

+ Returns + Erlang + monotonic time. Note that it is not uncommon with + negative values. +

+

Returns ERL_DRV_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + + + + ErlDrvTimeerl_drv_time_offset(ErlDrvTimeUnit time_unit) + Get current Time Offset + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time + converted into the time_unit passed as argument.

+

Returns ERL_DRV_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + + + + ErlDrvTimeerl_drv_convert_time_unit(ErlDrvTime val, ErlDrvTimeUnit from, ErlDrvTimeUnit to) + Convert time unit of a time value + + +

Arguments:

+ + val + Value to convert time unit for. + from + Time unit of val. + to + Time unit of returned value. + +

Converts the val value of time unit from to + the corresponding value of time unit to. The result is + rounded using the floor function.

+

Returns ERL_DRV_TIME_ERROR if called with an invalid + time unit argument.

+

See also:

+ + ErlDrvTime + ErlDrvTimeUnit + + + +
SEE ALSO diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 2d8706169f..420c9fea38 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -317,6 +317,17 @@ ok libraries might however fail if deprecated features are used.

+ Time Measurement +

Support for time measurement in NIF libraries: + + ErlNifTime + ErlNifTimeUnit + enif_monotonic_time() + enif_time_offset() + enif_convert_time_unit() +

+ + Long-running NIFs

Native functions @@ -560,6 +571,25 @@ typedef enum {

A native signed 64-bit integer type.

 ErlNifUInt64

A native unsigned 64-bit integer type.

 + + ErlNifTime + +

A signed 64-bit integer type for representation of time.

+ + ErlNifTimeUnit + +

An enumeration of time units supported by the NIF API:

+ + ERL_NIF_SEC +

Seconds

 + ERL_NIF_MSEC +

Milliseconds

 + ERL_NIF_USEC +

Microseconds

 + ERL_NIF_NSEC +

Nanoseconds

 + +
@@ -1486,6 +1516,88 @@ enif_map_iterator_destroy(env, &iter);

Same as erl_drv_tsd_set.

+ + + + ErlNifTimeenif_monotonic_time(ErlNifTimeUnit time_unit) + Get Erlang Monotonic Time + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

+ Returns + Erlang + monotonic time. Note that it is not uncommon with + negative values. +

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + + + + ErlNifTimeenif_time_offset(ErlNifTimeUnit time_unit) + Get current Time Offset + + +

Arguments:

+ + time_unit + Time unit of returned value. + +

Returns the current time offset between + Erlang monotonic time + and + Erlang system time + converted into the time_unit passed as argument.

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument, or if called from a thread that is not a + scheduler thread.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + + + + ErlNifTimeenif_convert_time_unit(ErlNifTime val, ErlNifTimeUnit from, ErlNifTimeUnit to) + Convert time unit of a time value + + +

Arguments:

+ + val + Value to convert time unit for. + from + Time unit of val. + to + Time unit of returned value. + +

Converts the val value of time unit from to + the corresponding value of time unit to. The result is + rounded using the floor function.

+

Returns ERL_NIF_TIME_ERROR if called with an invalid + time unit argument.

+

See also:

+ + ErlNifTime + ErlNifTimeUnit + + + +
SEE ALSO -- cgit v1.2.3 From eea5f896780e07f7ca76685061d01e7be5a7abaa Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Thu, 11 Sep 2014 18:26:26 +0200 Subject: erts, kernel: Add os:perf_counter function The perf_counter is a very very cheap and high resolution timer that can be used to timestamp system events. It does not have monoticity guarantees, but should on most OS's expose a monotonous time. A special instruction has been created for this counter to further speed up fetching it. OTP-12908 --- erts/doc/src/erlang.xml | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index d0d35ea25f..6915b35fcb 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -131,6 +131,17 @@ + perf_counter +

Symbolic representation of the performance counter + time unit used by the Erlang runtime system.

+ +

The perf_counter time unit behaves much in the same way + as the native time unit. That is it might differ inbetween + run-time restarts. You get values of this type by calling + os:perf_counter() +

+ +

The time_unit/0 type may be extended. Use -- cgit v1.2.3 From 664ed2a6fd2b324bb6b56db3d3eca853cfda8f61 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Fri, 12 Sep 2014 16:38:00 +0200 Subject: erts: Add microstate accounting Microstate accounting is a way to track which state the different threads within ERTS are in. The main usage area is to pin point performance bottlenecks by checking which states the threads are in and then from there figuring out why and where to optimize. Since checking whether microstate accounting is on or off is relatively expensive if done in a short loop only a few of the states are enabled by default and more states can be enabled through configure. I've done some benchmarking and the overhead with it turned off is not noticible and with it on it is a fraction of a percent. If you enable the extra states, depending on the benchmark, the ovehead when turned off is about 1% and when turned on somewhere inbetween 5-15%. OTP-12345 --- erts/doc/src/erlang.xml | 177 ++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 164 insertions(+), 13 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 6915b35fcb..ddca492040 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -5870,6 +5870,146 @@ true + Information about microstate accounting. + + +

+ Microstate accounting can be used to measure how much time the Erlang + runtime system spends doing various tasks. It is designed to be as + lightweight as possible, but there will be some overhead when this + is enabled. Microstate accounting is meant to be a profiling tool + to help figure out performance bottlenecks. + To start/stop/reset microstate_accounting you use + the system_flag + + microstate_accounting. +

+

+ erlang:statistics(microstate_accounting) returns a list of maps + representing some of the OS threads within ERTS. Each map contains + type and id fields that can be used to identify what + thread it is, and also a counters field that contains data about how + much time has been spent in the various states.

+ 
+> erlang:statistics(microstate_accounting).
+[#{counters => #{aux => 1899182914,
+                 check_io => 2605863602,
+                 emulator => 45731880463,
+                 gc => 1512206910,
+                 other => 5421338456,
+                 port => 221631,
+                 sleep => 5150294100},
+   id => 1,
+   type => scheduler}|...]
+
+

The time unit is the same as returned by + + os:perf_counter/0. + So to convert it to milliseconds you could do something like this:

+ 
+lists:map(
+  fun(#{ counters := Cnt } = M) ->
+          MsCnt = maps:map(fun(_K, PerfCount) ->
+                                   erlang:convert_time_unit(PerfCount, perf_counter, 1000)
+                           end, Cnt),
+         M#{ counters := MsCnt }
+  end, erlang:statistics(microstate_accounting)).
+
+

+ It is important to note that these values are not guaranteed to be + the exact time spent in each state. This is because of various + optimisation done in order to keep the overhead as small as possible. +

+ +

Currently the following MSAcc_Thread_Type are available:

+ + scheduler + The main execution threads that do most of the work. + asyncAsync threads are used by various + linked-in drivers (mainly the file drivers) do offload non-cpu + intensive work. + auxTakes care of any work that is not + specifically assigned to a scheduler. + +

Currently the following MSAcc_Thread_States are available. + All states are exclusive, meaning that a thread cannot be in two states + at once. So if you add the numbers of all counters in a thread + you will get the total run-time for that thread.

+ + aux + Time spent handling auxiliary jobs. + check_io + Time spent checking for new I/O events. + emulator + Time spent executing erlang processes. + gc + Time spent doing garbage collection. When extra states are + enabled this is the time spent doing non-fullsweep garbage + collections. + other + Time spent doing unaccounted things. + port + Time spent executing ports. + sleep + Time spent sleeping. + +

It is possible to add more fine grained MSAcc_Thread_States + through configure. + (e.g. ./configure --with-microstate-accounting=extra). + Enabling these states will cause a performance degradation when + microstate accounting is turned off and increase the overhead when + it is turned on.

+ + alloc + Time spent managing memory. Without extra states this time is + spread out over all other states. + bif + Time spent in bifs. Without extra states this time is part of + the emulator state. + busy_wait + Time spent busy waiting. This is also the state where a + scheduler no longer reports that it is active when using + + erlang:statistics(scheduler_wall_time). + So if you add all other states but this and sleep and then divide that + by all time in the thread you should get something very similar to the + scheduler_wall_time fraction. Without extra states this time is part + of the other state. + ets + Time spent executing ETS bifs. Without extra states this time is + part of the emulator state. + gc_full + Time spent doing fullsweep garbage collection. Without extra + states this time is part of the gc state. + nif + Time spent in nifs. Without extra states this time is part of + the emulator state. + send + Time spent sending messages (processes only). Without extra + states this time is part of the emulator state. + timers + Time spent managing timers. Without extra states this time is + part of the other state. + +

There is a utility module called + msacc in + runtime_tools that can be used to more easily analyse these + statistics.

+ +

+ Returns undefined if the system flag + + microstate_accounting + is turned off. +

+

The list of thread information is unsorted and may appear in + different order between calls.

+

The threads and states are subject to change without any + prior notice.

 + + + + Information about reductions. @@ -5887,7 +6027,7 @@ true - + Information about the run-queues.

@@ -5903,7 +6043,7 @@ true - + Information about the run-queue lengths.

@@ -5923,7 +6063,7 @@ true - + Information about runtime.

Returns information about runtime, in milliseconds.

@@ -5938,7 +6078,7 @@ true - + Information about each schedulers work time. @@ -6009,7 +6149,7 @@ ok - + Information about active processes and ports.

@@ -6027,7 +6167,7 @@ ok - + Information about the run-queue lengths.

@@ -6046,7 +6186,7 @@ ok - + Information about wall clock.

Returns information about wall clock. wall_clock can @@ -6280,6 +6420,17 @@ ok + Set system flag microstate_accounting +

+ Turns on/off microstate accounting measurements. By passing reset it is possible to reset + all counters to 0.

+

For more information see, + erlang:statistics(microstate_accounting). +

+ + + + Sets system flag min_heap_size.

Sets the default minimum heap size for processes. The size @@ -6294,7 +6445,7 @@ ok - + Sets system flag min_bin_vheap_size.

Sets the default minimum binary virtual heap size for @@ -6311,7 +6462,7 @@ ok - + Sets system flag multi_scheduling.

@@ -6349,7 +6500,7 @@ ok - + Sets system flag scheduler_bind_type. @@ -6467,7 +6618,7 @@ ok - + Sets system flag scheduler_wall_time.

Turns on or off scheduler wall time measurements.

@@ -6477,7 +6628,7 @@ ok - + Sets system flag schedulers_online.

@@ -6502,7 +6653,7 @@ ok - + Sets system flag trace_control_word.

Sets the value of the node trace control word to -- cgit v1.2.3 From 18f0707c218ebdeb6024ecffd7704d3582e0b91c Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Tue, 2 Feb 2016 16:20:19 +0100 Subject: Use nano second time unit in tracing --- erts/doc/src/erl_driver.xml | 5 +++-- erts/doc/src/erlang.xml | 9 +++++---- 2 files changed, 8 insertions(+), 6 deletions(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index e338e95938..34dc8af238 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1052,8 +1052,9 @@ typedef struct ErlIOVec {

This function is deprecated! Do not use it! - Use the documented - time measurement functionality + Use erl_drv_monotonic_time() + (perhaps in combination with + erl_drv_time_offset()) instead.

This function reads a timestamp into the memory pointed to by the parameter now. See the description of ErlDrvNowData for diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml index 79d3f66ea8..c9eb838230 100644 --- a/erts/doc/src/erlang.xml +++ b/erts/doc/src/erlang.xml @@ -7744,7 +7744,8 @@ ok

Timestamps in profile messages will use Erlang monotonic time. The time-stamp (Ts) has the same - format and value as produced by erlang:monotonic_time().

+ format and value as produced by + erlang:monotonic_time(nano_seconds).

runnable_procs @@ -7772,7 +7773,7 @@ ok Erlang monotonic time and a monotonically increasing integer. The time-stamp (Ts) has the same format and value - as produced by {erlang:monotonic_time(), + as produced by {erlang:monotonic_time(nano_seconds), erlang:unique_integer([monotonic])}.

 timestamp @@ -8161,7 +8162,7 @@ timestamp() -> Erlang monotonic time time-stamp in all trace messages. The time-stamp (Ts) has the same format and value as produced by - erlang:monotonic_time(). This flag overrides + erlang:monotonic_time(nano_seconds). This flag overrides the cpu_timestamp flag.

strict_monotonic_timestamp @@ -8171,7 +8172,7 @@ timestamp() -> monotonic time and a monotonically increasing integer in all trace messages. The time-stamp (Ts) has the same format and value as produced by - {erlang:monotonic_time(), + {erlang:monotonic_time(nano_seconds), erlang:unique_integer([monotonic])}. This flag overrides the cpu_timestamp flag.

-- cgit v1.2.3 From 7a319cd96f7f4869300b32442ebe892ae557f41c Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Mon, 8 Feb 2016 15:47:49 +0100 Subject: erts: Fix error cases in enif_get_list_length false if improper list false if length > UINT_MAX --- erts/doc/src/erl_nif.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'erts/doc') diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml index 420c9fea38..be0e406b9c 100644 --- a/erts/doc/src/erl_nif.xml +++ b/erts/doc/src/erl_nif.xml @@ -753,7 +753,7 @@ typedef enum { intenif_get_list_length(ErlNifEnv* env, ERL_NIF_TERM term, unsigned* len) Get the length of list term

Set *len to the length of list term and return true, - or return false if term is not a list.

 + or return false if term is not a proper list.

 intenif_get_long(ErlNifEnv* env, ERL_NIF_TERM term, long int* ip) Read an long integer term -- cgit v1.2.3