From e5875001247e6a6ac4f474157a51a8c54f94ae49 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Thu, 14 Mar 2013 16:01:25 +0100 Subject: Convert XML files to UTF-8 --- erts/doc/src/erl_driver.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index efe0483b31..7c74517b2e 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1,4 +1,4 @@ - + -- cgit v1.2.3 From a7db1f6930505ab6a70b0cb41a4c2d52a9448a08 Mon Sep 17 00:00:00 2001 From: olgeni Date: Wed, 7 Aug 2013 12:48:09 +0200 Subject: Misc. corrections for erl_driver(3) - Remove trailing whitespaces - Spelling fixes - Replace "deferred" with "deprecated" where applicable - Remove reference to non-existing "async_ready" entry point --- erts/doc/src/erl_driver.xml | 37 ++++++++++++++++++------------------- 1 file changed, 18 insertions(+), 19 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index efe0483b31..f52d973709 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -666,7 +666,7 @@ typedef struct ErlDrvBinary {

The ErlDrvData is a handle to driver-specific data, passed to the driver call-backs. It is a pointer, and is - most often type casted to a specific pointer in the driver.

+ most often type cast to a specific pointer in the driver.

 SysIOVec @@ -1014,7 +1014,7 @@ typedef struct ErlIOVec { Read a system timestamp -

This function reads a timestamp into the memory pointed to by +

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

The return value is 0 unless the now pointer is not @@ -1056,7 +1056,7 @@ typedef struct ErlIOVec { returned. Another thread may still be using the event object internally. To safely close an event object call driver_select with ERL_DRV_USE and on==0. That - will clear all events and then call + will clear all events and then call stop_select when it is safe to close the event object. ERL_DRV_USE should be set together with the first event @@ -1068,7 +1068,7 @@ typedef struct ErlIOVec {

ERL_DRV_USE was added in OTP release R13. Old drivers will still work as before. But it is recommended to update them to use ERL_DRV_USE and stop_select to make sure that event objects are closed in a safe way.

- +

The return value is 0 (failure, -1, only if the ready_input/ready_output is NULL).

@@ -1524,7 +1524,7 @@ typedef struct ErlIOVec {

This function removes a driver entry de previously added with add_driver_entry.

-

Driver entries added by the erl_ddll erlang interface can +

Driver entries added by the erl_ddll erlang interface can not be removed by using this interface.

 @@ -1758,7 +1758,7 @@ typedef struct ErlIOVec { 
 Term type            Argument(s)
 ===========================================
-ERL_DRV_NIL          
+ERL_DRV_NIL
 ERL_DRV_ATOM         ErlDrvTermData atom (from driver_mk_atom(char *string))
 ERL_DRV_INT          ErlDrvSInt integer
 ERL_DRV_UINT         ErlDrvUInt integer
@@ -1779,11 +1779,11 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	  signed integer data type ErlDrvSInt are 64 bits wide
 	  on a 64 bit runtime system and 32 bits wide on a 32 bit
 	  runtime system. They were introduced in erts version 5.6,
-	  and replaced some of the int arguments in the list above. 
+	  and replaced some of the int arguments in the list above.
 	

 	
The unsigned integer data type ErlDrvUInt64 and the
 	  signed integer data type ErlDrvSInt64 are always 64 bits
-	  wide. They were introduced in erts version 5.7.4. 
+	  wide. They were introduced in erts version 5.7.4.
 	

 
         
To build the tuple {tcp, Port, [100 | Binary]}, the
@@ -1879,7 +1879,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
       Send term data from driver to port owner
       
         
-	
driver_output_term() is deferred and will
+	
driver_output_term() is deprecated and will
 	            be removed in the OTP-R17 release. Use
 		    erl_drv_output_term()
 		    instead.

@@ -1937,7 +1937,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
       Send term data to other process than port owner process
       
         
-	
driver_send_term() is deferred and will
+	
driver_send_term() is deprecated and will
 	            be removed in the OTP-R17 release. Use
 		    erl_drv_send_term()
 		    instead.

@@ -1998,7 +1998,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
           The data should be freed in async_free, because it's
           called if driver_async_cancel is called.

         
When the async operation is done, ready_async driver
-          entry function is called. If async_ready is null in
+          entry function is called. If ready_async is null in
           the driver entry, the async_free function is called
           instead.

         
The return value is a handle to the asynchronous task, which
@@ -2035,7 +2035,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	   as of OTP-R15B driver_async_cancel() is deprecated, and
 	   scheduled for removal in OTP-R16. It will currently always fail,
 	   and return 0.

-	
driver_async_cancel() is deferred and will
+	
driver_async_cancel() is deprecated and will
 	            be removed in the OTP-R16 release.

 	
 
@@ -2048,7 +2048,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
         
         
This function locks the driver used by the port port
           in memory for the rest of the emulator process'
-          lifetime. After this call, the driver behaves as one of Erlang's 
+          lifetime. After this call, the driver behaves as one of Erlang's
           statically linked in drivers.

       
     
@@ -2076,7 +2076,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
           driver_entry).
           drv_data
           The driver defined handle that will be passed in subsequent
-           calls to driver call-backs. Note, that the 
+           calls to driver call-backs. Note, that the
           driver start call-back
            will not be called for this new driver instance.
            The driver defined handle is normally created in the
@@ -2284,7 +2284,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
           A thread identifier.
         
         
This function compares two thread identifiers for equality,
-	   and returns 0 it they aren't equal, and 
+	   and returns 0 it they aren't equal, and
 	   a value not equal to 0 if they are equal.

 	
A Thread identifier may be reused very quickly after
 	         a thread has terminated. Therefore, if a thread
@@ -2469,7 +2469,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
         
         
This function broadcasts on a condition variable. That is, if
 	   other threads are waiting on the condition variable being
-	   broadcasted on, all of them will be woken.
+	   broadcast on, all of them will be woken.
 	

         
This function is thread-safe.

       
@@ -2498,7 +2498,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	   the calling thread when calling this function.
 	

 	
erl_drv_cond_wait() might return even though
-	         no-one has signaled or broadcasted on the condition
+	         no-one has signaled or broadcast on the condition
 		 variable. Code calling erl_drv_cond_wait() should
 		 always be prepared for erl_drv_cond_wait()
 		 returning even though the condition that the thread was
@@ -2822,7 +2822,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
           A pointer to an output buffer.
           value_size
           A pointer to an integer. The integer is both used for
-	        passing input and output sizes (see below). 
+	        passing input and output sizes (see below).
 		
         
 	
This function retrieves the value of an environment variable.
@@ -2900,4 +2900,3 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
       Guide Ch. 3)

   
 
-
-- 
cgit v1.2.3


From 6d1f1d43aa0a9e0a2cb275ef760339c49518fc69 Mon Sep 17 00:00:00 2001
From: Patrik Nyblom 
Date: Fri, 16 Aug 2013 17:14:25 +0200
Subject: Create better distribution of files over async threads

The actual port id is used to create a key from the
pointer value which is the ErlDrvPort. To do this
a new driver api function driver_async_port_key is
added and the driver API minor version is updated.

The documentation is updated and the faulty description of
how to spread ports over async threads is updated to
use the new API.

Testcase also added.
---
 erts/doc/src/erl_driver.xml | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

(limited to 'erts/doc/src/erl_driver.xml')

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index f52d973709..540390e1b1 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -1981,7 +1981,7 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
           thread, the following call can be used:

         

         
@@ -2021,6 +2021,24 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
         
       
     
+    
+      unsigned intdriver_async_port_key (ErlDrvPort port)
+      Calculate an async key from an ErlDrvPort
+      
+        
+        
This function calculates a key for later use in driver_async(). The keys are
+        evenly distributed so that a fair mapping between port id's
+        and async thread id's is achieved.

+	
+	
Before OTP-R16, the actual port id could be used as a key
+	with proper casting, but after the rewrite of the port
+	subsystem, this is no longer the case. With this function, you
+	can achieve the same distribution based on port id's as before
+	OTP-R16.

+	
+      
+    
     
       intdriver_async_cancel(long id)
       Cancel an asynchronous call
@@ -2033,10 +2051,10 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	   The user had to implement synchronization of cancellation anyway.
 	   It also unnecessarily complicated the implementation. Therefore,
 	   as of OTP-R15B driver_async_cancel() is deprecated, and
-	   scheduled for removal in OTP-R16. It will currently always fail,
+	   scheduled for removal in OTP-R17. It will currently always fail,
 	   and return 0.

 	
driver_async_cancel() is deprecated and will
-	            be removed in the OTP-R16 release.

+	            be removed in the OTP-R17 release.

 	
 
       
-- 
cgit v1.2.3


From a209817dd8467a04be869541e7c31216dc4b0a12 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Bj=C3=B6rn-Egil=20Dahlberg?= 
Date: Tue, 3 Sep 2013 17:11:24 +0200
Subject: erts: Document erl_driver interface lock names

---
 erts/doc/src/erl_driver.xml | 78 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

(limited to 'erts/doc/src/erl_driver.xml')

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index efe0483b31..5cf0d2f47f 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -2889,8 +2889,84 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	beginning of this document.

       
     
-  
 
+	
+		char *erl_drv_cond_name(ErlDrvCond *cnd)
+		Get name of driver mutex.
+		
+			
+			
Arguments:

+			
+				cnd
+				A pointer to an initialized condition.
+			
+			

+				Returns a pointer to the name of the condition.
+			

+			
+				
This function is intended for debugging purposes only.

+			
+		
+	
+
+	
+		char *erl_drv_mutex_name(ErlDrvMutex *mtx)
+		Get name of driver mutex.
+		
+			
+			
Arguments:

+			
+				mtx
+				A pointer to an initialized mutex.
+			
+			

+				Returns a pointer to the name of the mutex.
+			

+			
+				
This function is intended for debugging purposes only.

+			
+		
+	
+
+	
+		char *erl_drv_rwlock_name(ErlDrvRWLock *rwlck)
+		Get name of driver mutex.
+		
+			
+			
Arguments:

+			
+				rwlck
+				A pointer to an initialized r/w-lock.
+			
+			

+				Returns a pointer to the name of the r/w-lock.
+			

+			
+				
This function is intended for debugging purposes only.

+			
+		
+	
+
+	
+		char *erl_drv_thread_name(ErlDrvTid tid)
+		Get name of driver mutex.
+		
+			
+			
Arguments:

+			
+				tid
+				A thread identifier.
+			
+			

+				Returns a pointer to the name of the thread.
+			

+			
+				
This function is intended for debugging purposes only.

+			
+		
+	
+
+  
   

     SEE ALSO
     
driver_entry(3),
-- 
cgit v1.2.3


From 8ff33cff02d01b2b4f20769cbd77c5ef23b01631 Mon Sep 17 00:00:00 2001
From: Steve Vinoski 
Date: Wed, 15 Jan 2014 10:13:11 -0500
Subject: remove deprecated driver_async_cancel function

Some time ago the driver_async_cancel function was deprecated and slated
for removal in R17. This commit removes the function along with its
associated tests and documentation, sets the
ERL_DRV_EXTENDED_MAJOR_VERSION to 3 and ERL_DRV_EXTENDED_MINOR_VERSION to
0, and modifies the sys_info_base_drv and sys_info_prev_drv tests in the
driver test suite to check version 3.0 instead of 2.0.
---
 erts/doc/src/erl_driver.xml | 28 +++-------------------------
 1 file changed, 3 insertions(+), 25 deletions(-)

(limited to 'erts/doc/src/erl_driver.xml')

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index b453a4861e..c2f7fa4588 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -745,7 +745,7 @@ typedef struct ErlIOVec {
           created and decrement it once when the port associated with
           the lock terminates. The emulator will also increment the
           reference count when an async job is enqueued and decrement
-          it after an async job has been invoked, or canceled. Besides
+          it after an async job has been invoked. Besides
           this, it is the responsibility of the driver to ensure that
           the reference count does not reach zero before the last use
           of the lock by the driver has been made. The reference count
@@ -1995,14 +1995,12 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
           async_invoke and async_free. It's typically a
           pointer to a structure that contains a pipe or event that
           can be used to signal that the async operation completed.
-          The data should be freed in async_free, because it's
-          called if driver_async_cancel is called.

+          The data should be freed in async_free.

         
When the async operation is done, ready_async driver
           entry function is called. If ready_async is null in
           the driver entry, the async_free function is called
           instead.

-        
The return value is a handle to the asynchronous task, which
-          can be used as argument to driver_async_cancel.

+        
The return value is a handle to the asynchronous task.

         
           
As of erts version 5.5.4.3 the default stack size for
             threads in the async-thread pool is 16 kilowords,
@@ -2039,26 +2037,6 @@ ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
 	
       
     
-    
-      intdriver_async_cancel(long id)
-      Cancel an asynchronous call
-      
-        
-        
This function used to cancel a scheduled asynchronous operation,
-	  if it was still in the queue. It returned 1 if it succeeded, and
-	  0 if it failed.

-	
Since it could not guarantee success, it was more or less useless.
-	   The user had to implement synchronization of cancellation anyway.
-	   It also unnecessarily complicated the implementation. Therefore,
-	   as of OTP-R15B driver_async_cancel() is deprecated, and
-	   scheduled for removal in OTP-R17. It will currently always fail,
-	   and return 0.

-	
driver_async_cancel() is deprecated and will
-	            be removed in the OTP-R17 release.

-	
-
-      
-    
     
       intdriver_lock_driver(ErlDrvPort port)
       Make sure the driver is never unloaded
-- 
cgit v1.2.3


From bc34b5dafaebf07d7185900310246f5752c0a6c4 Mon Sep 17 00:00:00 2001
From: Sverker Eriksson 
Date: Tue, 21 Jan 2014 12:21:11 +0100
Subject: erts: Add map construction to driver API

erl_drv_output_term() and erl_drv_send_term() can send messages
containing maps with the use of the new ERL_DRV_MAP.

The driver API minor version is updated as new functionality is added.
---
 erts/doc/src/erl_driver.xml | 29 ++++++++++++++++++++++++++---
 1 file changed, 26 insertions(+), 3 deletions(-)

(limited to 'erts/doc/src/erl_driver.xml')

diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index c2f7fa4588..710c9b19cf 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -4,7 +4,7 @@
 
   

     
-      20012013
+      20012014
       Ericsson AB. All Rights Reserved.
     
     
@@ -1742,15 +1742,19 @@ typedef struct ErlIOVec {
           term consists of one to four elements in the array. The
           term first has a term type, and then arguments. The
 	  port parameter specifies the sending port.

-        
Tuple and lists (with the exception of strings, see below),
+        
Tuples, maps and lists (with the exception of strings, see below),
           are built in reverse polish notation, so that to build a
           tuple, the elements are given first, and then the tuple
-          term, with a count. Likewise for lists.

+          term, with a count. Likewise for lists and maps.

         
A tuple must be specified with the number of elements. (The
           elements precede the ERL_DRV_TUPLE term.)

         
A list must be specified with the number of elements,
           including the tail, which is the last term preceding
           ERL_DRV_LIST.

+        
A map must be specified with the number of key-value pairs N.
+	  The key-value pairs must precede the ERL_DRV_MAP in this order:
+	  key1,value1,key2,value2,...,keyN,valueN.
+	  Duplicate keys are not allowed.

         
The special term ERL_DRV_STRING_CONS is used to
           "splice" in a string in a list, a string given this way is
           not a list per se, but the elements are elements of the
@@ -1774,6 +1778,7 @@ ERL_DRV_PID          ErlDrvTermData pid (from driver_connected(ErlDrvPort port)
 ERL_DRV_STRING_CONS  char *str, int len
 ERL_DRV_FLOAT        double *dbl
 ERL_DRV_EXT2TERM     char *buf, ErlDrvUInt len
+ERL_DRV_MAP          int sz

The unsigned integer data type ErlDrvUInt and the signed integer data type ErlDrvSInt are 64 bits wide @@ -1856,6 +1861,24 @@ ERL_DRV_EXT2TERM char *buf, ErlDrvUInt len }; erl_drv_output_term(driver_mk_port(drvport), spec, sizeof(spec) / sizeof(spec[0])); ]]> + +

To build the map #{key1 => 100, key2 => {200, 300}}, the + following call could be made.

+ + +

If you want to pass a binary and don't already have the content of the binary in an ErlDrvBinary, you can benefit from using ERL_DRV_BUF2BINARY instead of creating an ErlDrvBinary -- cgit v1.2.3 From cd69c2a54201b4e0c4ba86d4248937120e1957e7 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Wed, 8 Jan 2014 18:54:15 +0100 Subject: ose: Create OSE application Create an specific OSE application that mainly contains documentation around the OSE specific part of Erlang/OTP. --- erts/doc/src/erl_driver.xml | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 710c9b19cf..8da1836da7 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -1035,7 +1035,9 @@ 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.

+ Refer to the Win32 SDK documentation. + On Enea OSE, the receive function is used. See the for more details.

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

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

-

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

Some OS (Windows and Enea OSE) 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. -- cgit v1.2.3 From bf3222f10edbd1f6a5186c8fb35c29900ad0665f Mon Sep 17 00:00:00 2001 From: Rickard Green Date: Thu, 20 Mar 2014 19:01:11 +0100 Subject: Introduce minimum allowed major driver and nif versions on load --- erts/doc/src/erl_driver.xml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 8da1836da7..ad37813ac0 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -315,10 +315,13 @@ ERL_DRV_EXTENDED_MINOR_VERSION will be incremented when new features are added. The runtime system uses the minor version of the driver to determine what features to use. - The runtime system will refuse to load a driver if the major + The runtime system will normally refuse to load a driver if the major versions differ, or if the major versions are equal and the minor version used by the driver is greater than the one used - by the runtime system.

+ by the runtime system. Old drivers with lower major versions + will however be allowed after a bump of the major version during + a transition period of two major releases. Such old drivers might + however fail if deprecated features are used.

The emulator will refuse to load a driver that does not use the extended driver interface, to allow for 64-bit capable drivers, -- cgit v1.2.3 From 12d3d25535225934cb2190c82c1b5dae005f1cda Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Thu, 11 Sep 2014 17:47:32 +0200 Subject: erts: Remove enif_have_dirty_schedulers() and add 'dirty_scheduler_support' to ErlNifSysInfo --- erts/doc/src/erl_driver.xml | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index ad37813ac0..4a1aab75c7 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -546,6 +546,7 @@ typedef struct ErlDrvSysInfo { int scheduler_threads; int nif_major_version; int nif_minor_version; + int dirty_scheduler_support; } ErlDrvSysInfo; @@ -610,6 +611,10 @@ typedef struct ErlDrvSysInfo { nif_minor_version The value of ERL_NIF_MINOR_VERSION when the runtime system was compiled. + dirty_scheduler_support + A value != 0 if the runtime system has support for dirty scheduler threads; + otherwise 0. + ErlDrvBinary -- cgit v1.2.3 From 024ad413bd20219e92c7642e4c29689886bf96ce Mon Sep 17 00:00:00 2001 From: Steve Vinoski Date: Fri, 17 Oct 2014 15:50:41 -0400 Subject: Clarify docs for driver_async() return value The documentation for driver_async() still referred to the return value of the function as a "handle", which is no longer meaningful since driver_async_cancel() was deprecated and removed. Modify the documentation to simply indicate that the driver_async() return value will be -1 if it fails. --- erts/doc/src/erl_driver.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 4a1aab75c7..77fc906aca 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -2033,7 +2033,8 @@ ERL_DRV_MAP int sz entry function is called. If ready_async is null in the driver entry, the async_free function is called instead.

-

The return value is a handle to the asynchronous task.

+

The return value is -1 if the driver_async call + fails.

As of erts version 5.5.4.3 the default stack size for threads in the async-thread pool is 16 kilowords, -- cgit v1.2.3 From 738c34d4bb8f1a3811acd00af8c6c12107f8315b Mon Sep 17 00:00:00 2001 From: Bruce Yinhe Date: Thu, 18 Jun 2015 11:31:02 +0200 Subject: Change license text to APLv2 --- erts/doc/src/erl_driver.xml | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 77fc906aca..1f7fe0f961 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -8,16 +8,17 @@ Ericsson AB. All Rights Reserved. - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. -- cgit v1.2.3 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/erl_driver.xml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') 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. -- cgit v1.2.3 From 5ae78de4e4f6e220e29ad2f54b95a0098da4b365 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Mon, 12 Oct 2015 12:12:27 +0200 Subject: [erts] Correct documentation Fix mistakes found by 'xmllint'. --- erts/doc/src/erl_driver.xml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 1f7fe0f961..42b6a3bfef 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -4,7 +4,7 @@

- 20012014 + 20012015 Ericsson AB. All Rights Reserved. @@ -223,7 +223,7 @@ asynchronous function calls, using a thread pool provided by Erlang. There is also a select call, that can be used for asynchronous drivers. - Multi-threading + Multi-threading

A POSIX thread like API for multi-threading is provided. The Erlang driver thread API only provide a subset of the functionality @@ -297,7 +297,7 @@

A driver can add and later remove drivers.

 Monitoring processes

A driver can monitor a process that does not own a port.

 - Version management + Version management

Version management is enabled for drivers that have set the extended_marker @@ -384,12 +384,12 @@

Rewrite driver callback - control + control to use return type ErlDrvSSizeT instead of int.

Rewrite driver callback - call + call to use return type ErlDrvSSizeT instead of int.

@@ -407,19 +407,19 @@

Driver callback - output + output now gets ErlDrvSizeT as 3rd argument instead of previously int.

Driver callback - control + control now gets ErlDrvSizeT as 4th and 6th arguments instead of previously int.

Driver callback - call + call now gets ErlDrvSizeT as 4th and 6th arguments instead of previously int.

-- cgit v1.2.3 From 01cc99b35c00be86d832693776ee8ed880b59882 Mon Sep 17 00:00:00 2001 From: Sverker Eriksson Date: Mon, 8 Dec 2014 20:36:28 +0100 Subject: erts: Make key argument constant for erl_drv_{get|put}env This should be a harmless and compatible API change. --- erts/doc/src/erl_driver.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 1f7fe0f961..d829aeda10 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -2811,7 +2811,7 @@ ERL_DRV_MAP int sz - interl_drv_putenv(char *key, char *value) + interl_drv_putenv(const char *key, char *value) Set the value of an environment variable @@ -2840,7 +2840,7 @@ ERL_DRV_MAP int sz - interl_drv_getenv(char *key, char *value, size_t *value_size) + interl_drv_getenv(const char *key, char *value, size_t *value_size) Get the value of an environment variable -- 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/erl_driver.xml | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) (limited to 'erts/doc/src/erl_driver.xml') 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/src/erl_driver.xml') 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 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 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) (limited to 'erts/doc/src/erl_driver.xml') 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 -- 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 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') 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 -- cgit v1.2.3 From 6664eed554974336909d3ffe03f20349cc4c38fd Mon Sep 17 00:00:00 2001 From: Henrik Nord Date: Tue, 15 Mar 2016 15:19:56 +0100 Subject: update copyright-year --- erts/doc/src/erl_driver.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 241d4131d5..175b7f6bfb 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -4,7 +4,7 @@

- 20012015 + 20012016 Ericsson AB. All Rights Reserved. -- cgit v1.2.3 From 7b5ca88b32c22a7f1a3152265d8d73418013b1c0 Mon Sep 17 00:00:00 2001 From: Lukas Larsson Date: Fri, 13 May 2016 10:38:20 +0200 Subject: erts: Fix doc xml errors --- erts/doc/src/erl_driver.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'erts/doc/src/erl_driver.xml') diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml index 175b7f6bfb..82215ead46 100644 --- a/erts/doc/src/erl_driver.xml +++ b/erts/doc/src/erl_driver.xml @@ -348,14 +348,14 @@ all will work as before.

Time Measurement -

Support for time measurement in drivers: +

Support for time measurement in drivers:

ErlDrvTime ErlDrvTimeUnit erl_drv_monotonic_time() erl_drv_time_offset() erl_drv_convert_time_unit() -

+
-- cgit v1.2.3