← Back to branch summary

~clint-fewbar/ubuntu/precise/erlang/merge-15b

« back to all changes in this revision

Viewing changes to erts/doc/src/erl_driver.xml

  • Committer: Package Import Robot
  • Author(s): Sergei Golovan
  • Date: 2011-12-15 19:20:10 UTC
  • mfrom: (1.1.18) (3.5.15 sid)
  • mto: (3.5.16 sid)
  • mto: This revision was merged to the branch mainline in revision 33.
  • Revision ID: package-import@ubuntu.com-20111215192010-jnxcfe3tbrpp0big
Tags: 1:15.b-dfsg-1
* New upstream release.
* Upload to experimental because this release breaks external drivers
  API along with ABI, so several applications are to be fixed.
* Removed SSL patch because the old SSL implementation is removed from
  the upstream distribution.
* Removed never used patch which added native code to erlang beam files.
* Removed the erlang-docbuilder binary package because the docbuilder
  application was dropped by upstream.
* Documented dropping ${erlang-docbuilder:Depends} substvar in
  erlang-depends(1) manpage.
* Made erlang-base and erlang-base-hipe provide virtual package
  erlang-abi-15.b (the number means the first erlang version, which
  provides current ABI).

Show diffs side-by-side

added added

removed removed

Lines of Context:
erts/doc/src/erl_driver.xml
4
4
<cref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>2001</year><year>2010</year>
 
7
      <year>2001</year><year>2011</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
37
37
    <p>As of erts version 5.5.3 the driver interface has been extended
38
38
      (see <seealso marker="driver_entry#extended_marker">extended marker</seealso>).
39
39
      The extended interface introduce
40
 
      <seealso marker="erl_driver#version_management">version management</seealso>,
 
40
      <seealso marker="#version_management">version management</seealso>,
41
41
      the possibility to pass capability flags
42
42
      (see <seealso marker="driver_entry#driver_flags">driver flags</seealso>)
43
43
      to the runtime system at driver initialization, and some new
44
44
      driver API functions.      </p>
45
45
    <note>
46
 
      <p>Old drivers (compiled with an <c>erl_driver.h</c> from an
47
 
        earlier erts version than 5.5.3) have to be recompiled
48
 
        (but does not have to use the extended interface).</p>
 
46
      <p>As of erts version 5.9 old drivers has to be recompiled
 
47
      and has to use the extended interface. They also has to be
 
48
      adjusted to the
 
49
      <seealso marker="#rewrites_for_64_bits">64-bit capable driver interface.
 
50
      </seealso>
 
51
      </p>
49
52
    </note>
50
53
    <p>The driver calls back to the emulator, using the API
51
54
      functions declared in <c>erl_driver.h</c>. They are used for
56
59
      instance is connected to an Erlang port. Every port has a port
57
60
      owner process. Communication with the port is normally done
58
61
      through the port owner process.</p>
59
 
    <p>Most of the functions takes the <c>port</c> handle as an
 
62
    <p>Most of the functions take the <c>port</c> handle as an
60
63
      argument. This identifies the driver instance. Note that this
61
64
      port handle must be stored by the driver, it is not given when
62
65
      the driver is called from the emulator (see
63
66
      <seealso marker="driver_entry#emulator">driver_entry</seealso>).</p>
64
 
    <p>Some of the functions takes a parameter of type
 
67
    <p>Some of the functions take a parameter of type
65
68
      <c>ErlDrvBinary</c>, a driver binary. It should be both
66
 
      allocated and freed by the caller. Using a binary directly avoid
 
69
      allocated and freed by the caller. Using a binary directly avoids
67
70
      one extra copying of data.</p>
68
 
    <p>Many of the output functions has a "header buffer", with
 
71
    <p>Many of the output functions have a "header buffer", with
69
72
      <c>hbuf</c> and <c>hlen</c> parameters. This buffer is sent as a
70
73
      list before the binary (or list, depending on port mode) that is
71
74
      sent. This is convenient when matching on messages received from
92
95
      with SMP support without being rewritten if driver
93
96
      level locking is used.</p>
94
97
    <note>
95
 
      <p>It is assumed that drivers does not access other drivers. If
 
98
      <p>It is assumed that drivers do not access other drivers. If
96
99
        drivers should access each other they have to provide their own
97
100
        mechanism for thread safe synchronization. Such "inter driver
98
101
        communication" is strongly discouraged.</p>
113
116
        call-backs may be made from different threads.</p>
114
117
    </note>
115
118
    <p>Most functions in this API are <em>not</em> thread-safe, i.e.,
116
 
      they may <em>not</em> be called from an arbitrary thread. Function
 
119
      they may <em>not</em> be called from an arbitrary thread. Functions
117
120
      that are not documented as thread-safe may only be called from
118
121
      driver call-backs or function calls descending from a driver
119
122
      call-back call. Note that driver call-backs may be called from
120
123
      different threads. This, however, is not a problem for any
121
 
      functions in this API, since the emulator have control over
 
124
      function in this API, since the emulator has control over
122
125
      these threads.</p>
123
126
    <note>
124
127
      <p>Functions not explicitly documented as thread-safe are
155
158
          more information.</p>
156
159
      </item>
157
160
      <tag>Output functions</tag>
158
 
      <item>With the output functions, the driver sends data back
 
161
      <item>With the output functions, the driver sends data back to
159
162
       the emulator. They will be received as messages by the port owner
160
163
       process, see <c>open_port/2</c>. The vector function and the
161
 
       function taking a driver binary is faster, because that avoid
 
164
       function taking a driver binary are faster, because they avoid
162
165
       copying the data buffer. There is also a fast way of sending
163
166
       terms from the driver, without going through the binary term
164
167
       format.</item>
193
196
         use functionality from the POSIX thread API or the Windows
194
197
         native thread API.
195
198
      </p>
196
 
      <p>The Erlang driver thread API only return error codes when it is
 
199
      <p>The Erlang driver thread API only returns error codes when it is
197
200
         reasonable to recover from an error condition. If it isn't reasonable
198
201
         to recover from an error condition, the whole runtime system is
199
202
         terminated. For example, if a create mutex operation fails, an error
200
203
         code is returned, but if a lock operation on a mutex fails, the
201
204
         whole runtime system is terminated.
202
205
      </p>
203
 
      <p>Note that there exist no "condition variable wait with timeout" in
 
206
      <p>Note that there exists no "condition variable wait with timeout" in
204
207
         the Erlang driver thread API. This is due to issues with
205
208
         <c>pthread_cond_timedwait()</c>. When the system clock suddenly
206
209
         is changed, it isn't always guaranteed that you will wake up from
241
244
         to give you better error reports.
242
245
      </p>
243
246
      </item>
244
 
      <tag>Adding / remove drivers</tag>
245
 
      <item>A driver can add and later remove drivers.</item>
 
247
      <tag>Adding / removing drivers</tag>
 
248
      <item><p>A driver can add and later remove drivers.</p></item>
246
249
      <tag>Monitoring processes</tag>
247
 
      <item>A driver can monitor a process that does not own a port.</item>
 
250
      <item><p>A driver can monitor a process that does not own a port.</p></item>
248
251
      <tag><marker id="version_management">Version management</marker></tag>
249
252
      <item>
250
253
        <p>Version management is enabled for drivers that have set the
262
265
          could, under rare circumstances, mean that drivers have to
263
266
          be slightly modified. If so, this will of course be documented.
264
267
          <c>ERL_DRV_EXTENDED_MINOR_VERSION</c> will be incremented when
265
 
          new features are added. The runtime system use the minor version
 
268
          new features are added. The runtime system uses the minor version
266
269
          of the driver to determine what features to use.
267
270
          The runtime system will refuse to load a driver if the major
268
271
          versions differ, or if the major versions are equal and the
269
272
          minor version used by the driver is greater than the one used
270
273
          by the runtime system.</p>
271
 
        <p>The emulator tries to check that a driver that doesn't use the
272
 
          extended driver interface isn't incompatible when loading it.
273
 
          It can, however, not make sure that it isn't incompatible. Therefore,
274
 
          when loading a driver that doesn't use the extended driver
275
 
          interface, there is a risk that it will be loaded also when
276
 
          the driver is incompatible. When the driver use the extended driver
277
 
          interface, the emulator can verify that it isn't of an incompatible
278
 
          driver version. You are therefore advised to use the extended driver
279
 
          interface.</p>
 
274
        <p>The emulator will refuse to load a driver that does not use
 
275
          the extended driver interface since,
 
276
          to allow for 64-bit capable drivers,
 
277
          incompatible type changes for the callbacks
 
278
          <seealso marker="driver_entry#output">output</seealso>,
 
279
          <seealso marker="driver_entry#control">control</seealso> and
 
280
          <seealso marker="driver_entry#call">call</seealso>
 
281
          were introduced in release R15B. A driver written
 
282
          with the old types would compile with warnings and when
 
283
          called return garbage sizes to the emulator causing it
 
284
          to read random memory and create huge incorrect result blobs.</p>
 
285
        <p>Therefore it is not enough to just recompile drivers written with
 
286
          version management for pre-R15B types; the types has to be changed
 
287
          in the driver suggesting other rewrites especially regarding
 
288
          size variables. Investigate all warnings when recompiling!</p>
 
289
        <p>Also, the API driver functions <c>driver_output*</c>,
 
290
          <c>driver_vec_to_buf</c>, <c>driver_alloc/realloc*</c>
 
291
          and the <c>driver_*</c> queue functions were changed to have
 
292
          larger length arguments and return values. This is a
 
293
          lesser problem since code that passes smaller types
 
294
          will get them auto converted in the calls and as long as
 
295
          the driver does not handle sizes that overflow an <c>int</c>
 
296
          all will work as before.</p>
 
297
      </item>
 
298
    </taglist>
 
299
  </section>
 
300
 
 
301
  <section>
 
302
    <marker id="rewrites_for_64_bits"/>
 
303
    <title>
 
304
      REWRITES FOR 64-BIT DRIVER INTERFACE
 
305
    </title>
 
306
    <p>
 
307
      For erts-5.9 two new integer types
 
308
      <seealso marker="#ErlDrvSizeT">ErlDrvSizeT</seealso> and
 
309
      <seealso marker="#ErlDrvSSizeT">ErlDrvSSizeT</seealso>
 
310
      were introduced that can hold 64-bit sizes if necessary.
 
311
    </p>
 
312
    <p>
 
313
      To not update a driver and just recompile it probably works
 
314
      when building for a 32-bit machine creating a false sense of security.
 
315
      Hopefully that will generate many important warnings.
 
316
      But when recompiling the same driver later on for a 64-bit machine
 
317
      there <em>will</em> be warnings and almost certainly crashes.
 
318
      So it is a BAD idea to postpone updating the driver and
 
319
      not fixing the warnings!
 
320
    </p>
 
321
    <p>
 
322
      When recompiling with <c>gcc</c> use the <c>-Wstrict-prototypes</c>
 
323
      flag to get better warnings. Try to find a similar flag if you
 
324
      are using some other compiler.
 
325
    </p>
 
326
    <p>
 
327
      Here follows a checklist for rewriting a pre erts-5.9 driver,
 
328
      most important first.
 
329
    </p>
 
330
    <taglist>
 
331
      <tag>Return types for driver callbacks</tag>
 
332
      <item>
 
333
        <p>
 
334
          Rewrite driver callback
 
335
          <c><seealso marker="driver_entry#control">control</seealso></c>
 
336
          to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>.
 
337
        </p>
 
338
        <p>
 
339
          Rewrite driver callback
 
340
          <c><seealso marker="driver_entry#call">call</seealso></c>
 
341
          to use return type <c>ErlDrvSSizeT</c> instead of <c>int</c>.
 
342
        </p>
 
343
        <note>
 
344
          <p>
 
345
            These changes are essential to not crash the emulator
 
346
            or worse cause malfunction.
 
347
            Without them a driver may return garbage in the high 32 bits
 
348
            to the emulator causing it to build a huge result from random
 
349
            bytes either crashing on memory allocation or succeeding with
 
350
            a random result from the driver call.
 
351
          </p>
 
352
        </note>
 
353
      </item>
 
354
      <tag>Arguments to driver callbacks</tag>
 
355
      <item>
 
356
        <p>
 
357
          Driver callback
 
358
          <c><seealso marker="driver_entry#output">output</seealso></c>
 
359
          now gets <c>ErlDrvSizeT</c> as 3:rd argument instead
 
360
          of previously <c>int</c>.
 
361
        </p>
 
362
        <p>
 
363
          Driver callback
 
364
          <c><seealso marker="driver_entry#control">control</seealso></c>
 
365
          now gets <c>ErlDrvSizeT</c> as 4:th and 6:th arguments instead
 
366
          of previously <c>int</c>.
 
367
        </p>
 
368
        <p>
 
369
          Driver callback
 
370
          <c><seealso marker="driver_entry#call">call</seealso></c>
 
371
          now gets <c>ErlDrvSizeT</c> as 4:th and 6:th arguments instead
 
372
          of previously <c>int</c>.
 
373
        </p>
 
374
        <p>
 
375
          Sane compiler's calling conventions probably make these changes
 
376
          necessary only for a driver to handle data chunks that require
 
377
          64-bit size fields (mostly larger than 2 GB since that is what
 
378
          an <c>int</c> of 32 bits can hold). But it is possible to think
 
379
          of non-sane calling conventions that would make the driver
 
380
          callbacks mix up the arguments causing malfunction.
 
381
        </p>
 
382
        <note>
 
383
          <p>
 
384
            The argument type change is from signed to unsigned which
 
385
            may cause problems for e.g. loop termination conditions or
 
386
            error conditions if you just change the types all over the place.
 
387
          </p>
 
388
        </note>
 
389
      </item>
 
390
      <tag>Larger <c>size</c> field in <c>ErlIOVec</c></tag>
 
391
      <item>
 
392
        <p>
 
393
          The <c>size</c> field in
 
394
          <seealso marker="#ErlIOVec"><c>ErlIOVec</c></seealso>
 
395
          has been changed to <c>ErlDrvSizeT</c> from <c>int</c>.
 
396
          Check all code that use that field.
 
397
        </p>
 
398
        <p>
 
399
          Automatic type casting probably makes these changes necessary only
 
400
          for a driver that encounters sizes larger than 32 bits.
 
401
        </p>
 
402
        <note>
 
403
          <p>
 
404
            The <c>size</c> field changed from signed to unsigned which
 
405
            may cause problems for e.g. loop termination conditions or
 
406
            error conditions if you just change the types all over the place.
 
407
          </p>
 
408
        </note>
 
409
      </item>
 
410
      <tag>Arguments and return values in the driver API</tag>
 
411
      <item>
 
412
        <p>
 
413
          Many driver API functions has changed argument type
 
414
          and/or return value to <c>ErlDrvSizeT</c> from mostly <c>int</c>.
 
415
          Automatic type casting probably makes these changes necessary only
 
416
          for a driver that encounters sizes larger than 32 bits.
 
417
        </p>
 
418
        <taglist>
 
419
          <tag><seealso marker="#driver_output">driver_output</seealso></tag>
 
420
          <item>3:rd argument</item>
 
421
          <tag><seealso marker="#driver_output2">driver_output2</seealso></tag>
 
422
          <item>3:rd and 5:th arguments</item>
 
423
          <tag>
 
424
          <seealso marker="#driver_output_binary">driver_output_binary</seealso>
 
425
          </tag>
 
426
          <item>3:rd 5:th and 6:th arguments</item>
 
427
          <tag><seealso marker="#driver_outputv">driver_outputv</seealso></tag>
 
428
          <item>3:rd and 5:th arguments</item>
 
429
          <tag>
 
430
          <seealso marker="#driver_vec_to_buf">driver_vec_to_buf</seealso>
 
431
          </tag>
 
432
          <item>3:rd argument and return value</item>
 
433
          <tag><seealso marker="#driver_alloc">driver_alloc</seealso></tag>
 
434
          <item>1:st argument</item>
 
435
          <tag><seealso marker="#driver_realloc">driver_realloc</seealso></tag>
 
436
          <item>2:nd argument</item>
 
437
          <tag>
 
438
          <seealso marker="#driver_alloc_binary">driver_alloc_binary</seealso>
 
439
          </tag>
 
440
          <item>1:st argument</item>
 
441
          <tag>
 
442
          <seealso marker="#driver_realloc_binary">driver_realloc_binary</seealso>
 
443
          </tag>
 
444
          <item>2:nd argument</item>
 
445
          <tag><seealso marker="#driver_enq">driver_enq</seealso></tag>
 
446
          <item>3:rd argument</item>
 
447
          <tag><seealso marker="#driver_pushq">driver_pushq</seealso></tag>
 
448
          <item>3:rd argument</item>
 
449
          <tag><seealso marker="#driver_deq">driver_deq</seealso></tag>
 
450
          <item>2:nd argument and return value</item>
 
451
          <tag><seealso marker="#driver_sizeq">driver_sizeq</seealso></tag>
 
452
          <item>return value</item>
 
453
          <tag><seealso marker="#driver_enq_bin">driver_enq_bin</seealso></tag>
 
454
          <item>3:rd and 4:th argument</item>
 
455
          <tag><seealso marker="#driver_pushq_bin">driver_pushq_bin</seealso></tag>
 
456
          <item>3:rd and 4:th argument</item>
 
457
          <tag><seealso marker="#driver_enqv">driver_enqv</seealso></tag>
 
458
          <item>3:rd argument</item>
 
459
          <tag><seealso marker="#driver_pushqv">driver_pushqv</seealso></tag>
 
460
          <item>3:rd argument</item>
 
461
          <tag><seealso marker="#driver_peekqv">driver_peekqv</seealso></tag>
 
462
          <item>return value</item>
 
463
        </taglist>
 
464
        <note>
 
465
          <p>
 
466
            This is a change from signed to unsigned which
 
467
            may cause problems for e.g. loop termination conditions and
 
468
            error conditions if you just change the types all over the place.
 
469
          </p>
 
470
        </note>
280
471
      </item>
281
472
    </taglist>
282
473
  </section>
285
476
    <title>DATA TYPES</title>
286
477
 
287
478
    <taglist>
288
 
     <tag><marker id="ErlDrvSysInfo"/>ErlDrvSysInfo</tag>
 
479
      <tag><marker id="ErlDrvSizeT"/>ErlDrvSizeT</tag>
 
480
      <item><p>An unsigned integer type to be used as <c>size_t</c></p></item>
 
481
      <tag><marker id="ErlDrvSSizeT"/>ErlDrvSSizeT</tag>
 
482
      <item><p>A signed integer type the size of <c>ErlDrvSizeT</c></p></item>
 
483
      <tag><marker id="ErlDrvSysInfo"/>ErlDrvSysInfo</tag>
289
484
      <item>
290
485
      <p/>
291
486
      <code type="none">
309
504
        <seealso marker="#driver_system_info">driver_system_info()</seealso>
310
505
        will write the system information when passed a reference to
311
506
        a <c>ErlDrvSysInfo</c> structure. A description of the
312
 
        fields in the structure follow:
 
507
        fields in the structure follows:
313
508
      </p>
314
509
      <taglist>
315
510
        <tag><c>driver_major_version</c></tag>
332
527
        <tag><c>erts_version</c></tag>
333
528
        <item>A string containing the version number of the runtime system
334
529
           (the same as returned by
335
 
          <seealso marker="erts:erlang#system_info_version">erlang:system_info(version)</seealso>).
 
530
          <seealso marker="erlang#system_info_version">erlang:system_info(version)</seealso>).
336
531
        </item>
337
532
        <tag><c>otp_release</c></tag>
338
533
        <item>A string containing the OTP release number
339
534
           (the same as returned by
340
 
          <seealso marker="erts:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>).
341
 
        </item>
342
 
        <tag><c>thread_support</c></tag>
343
 
        <item>A value <c>!= 0</c> if the runtime system has thread support;
344
 
           otherwise, <c>0</c>.
345
 
        </item>
346
 
        <tag><c>smp_support</c></tag>
347
 
        <item>A value <c>!= 0</c> if the runtime system has SMP support;
348
 
           otherwise, <c>0</c>.
 
535
          <seealso marker="erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>).
349
536
        </item>
350
537
        <tag><c>thread_support</c></tag>
351
538
        <item>A value <c>!= 0</c> if the runtime system has thread support;
359
546
        <item>The number of async threads in the async thread pool used
360
547
           by <seealso marker="#driver_async">driver_async()</seealso>
361
548
           (the same as returned by
362
 
          <seealso marker="erts:erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>).
 
549
          <seealso marker="erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>).
363
550
        </item>
364
551
        <tag><c>scheduler_threads</c></tag>
365
552
        <item>The number of scheduler threads used by the runtime system
366
553
           (the same as returned by
367
 
          <seealso marker="erts:erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>).
 
554
          <seealso marker="erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>).
368
555
        </item>
369
556
        <tag><c>nif_major_version</c></tag>
370
557
        <item>The value of <c>ERL_NIF_MAJOR_VERSION</c> when the runtime system was compiled.
379
566
      <p/>
380
567
      <code type="none">
381
568
typedef struct ErlDrvBinary {
382
 
   int orig_size;
 
569
   ErlDrvSint orig_size;
383
570
   char orig_bytes[];
384
571
} ErlDrvBinary;
385
572
</code>
401
588
            <seealso marker="#driver_binary_dec_refc">driver_binary_dec_refc()</seealso>.</p>
402
589
        </note>
403
590
        <p>Some driver calls, such as <c>driver_enq_binary</c>,
404
 
          increments the driver reference count, and others, such as
405
 
          <c>driver_deq</c> decrements it.</p>
 
591
          increment the driver reference count, and others, such as
 
592
          <c>driver_deq</c> decrement it.</p>
406
593
        <p>Using a driver binary instead of a normal buffer, is often
407
594
          faster, since the emulator doesn't need to copy the data,
408
595
          only the pointer is used.</p>
415
602
          <c>driver_outputv</c> calls, and in the queue. Also the
416
603
          driver call-back <seealso marker="driver_entry#outputv">outputv</seealso> uses driver
417
604
          binaries.</p>
418
 
        <p>If the driver of some reason or another, wants to keep a
 
605
        <p>If the driver for some reason or another, wants to keep a
419
606
          driver binary around, in a static variable for instance, the
420
607
          reference count should be incremented,
421
608
          and the binary can later be freed in the <seealso marker="driver_entry#stop">stop</seealso> call-back, with
423
610
        <p>Note that since a driver binary is shared by the driver and
424
611
          the emulator, a binary received from the emulator or sent to
425
612
          the emulator, must not be changed by the driver.</p>
426
 
        <p>From erts version 5.5 (OTP release R11B), orig_bytes is 
 
613
        <p>Since erts version 5.5 (OTP release R11B), orig_bytes is
427
614
          guaranteed to be properly aligned for storage of an array of
428
615
          doubles (usually 8-byte aligned).</p>
429
616
      </item>
431
618
      <item>
432
619
        <p>The <c>ErlDrvData</c> is a handle to driver-specific data,
433
620
          passed to the driver call-backs. It is a pointer, and is
434
 
          most often casted to a specific pointer in the driver.</p>
 
621
          most often type casted to a specific pointer in the driver.</p>
435
622
      </item>
436
623
      <tag>SysIOVec</tag>
437
624
      <item>
445
632
      <code type="none">
446
633
typedef struct ErlIOVec {
447
634
  int vsize;
448
 
  int size;
 
635
  ErlDrvSizeT size;
449
636
  SysIOVec* iov;
450
 
  >ErlDrvBinary** binv;
 
637
  ErlDrvBinary** binv;
451
638
} ErlIOVec;
452
639
</code>
453
640
        <p>The I/O vector used by the emulator and drivers, is a list
495
682
          Currently, the only port specific data that the emulator
496
683
          associates with the port data lock is the driver queue.</p>
497
684
        <p>Normally a driver instance does not have a port data lock. If
498
 
          the driver instance want to use a port data lock, it has to
 
685
          the driver instance wants to use a port data lock, it has to
499
686
          create the port data lock by calling
500
687
          <seealso marker="#driver_pdl_create">driver_pdl_create()</seealso>.
501
688
          <em>NOTE</em>: Once the port data lock has been created, every
502
 
          access to data associated with the port data lock have to be done
 
689
          access to data associated with the port data lock has to be done
503
690
          while having the port data lock locked. The port data lock is
504
691
          locked, and unlocked, respectively, by use of
505
692
          <seealso marker="#driver_pdl_lock">driver_pdl_lock()</seealso>, and
506
693
          <seealso marker="#driver_pdl_unlock">driver_pdl_unlock()</seealso>.</p>
507
694
        <p>A port data lock is reference counted, and when the reference
508
 
          count reach zero, it will be destroyed. The emulator will at
 
695
          count reaches zero, it will be destroyed. The emulator will at
509
696
          least increment the reference count once when the lock is
510
697
          created and decrement it once when the port associated with
511
698
          the lock terminates. The emulator will also increment the
545
732
        </p>
546
733
        <taglist>
547
734
          <tag>suggested_stack_size</tag>
548
 
          <item>A suggestion, in kilo-words, on how large stack to use. A value less
 
735
          <item>A suggestion, in kilo-words, on how large a stack to use. A value less
549
736
                than zero means default size.
550
737
          </item>
551
738
        </taglist>
638
825
      </desc>
639
826
    </func>
640
827
    <func>
641
 
      <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, int len)</nametext></name>
 
828
      <name><ret>int</ret><nametext>driver_output(ErlDrvPort port, char *buf, ErlDrvSizeT len)</nametext></name>
642
829
      <fsummary>Send data from driver to port owner</fsummary>
643
830
      <desc>
644
831
        <marker id="driver_output"></marker>
648
835
          opened.</p>
649
836
        <p>The data is queued in the port owner process' message
650
837
          queue. Note that this does not yield to the emulator. (Since
651
 
          the driver and the emulator runs in the same thread.)</p>
 
838
          the driver and the emulator run in the same thread.)</p>
652
839
        <p>The parameter <c>buf</c> points to the data to send, and
653
840
          <c>len</c> is the number of bytes.</p>
654
841
        <p>The return value for all output functions is 0. (Unless the
658
845
      </desc>
659
846
    </func>
660
847
    <func>
661
 
      <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, int hlen, char *buf, int len)</nametext></name>
 
848
      <name><ret>int</ret><nametext>driver_output2(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, char *buf, ErlDrvSizeT len)</nametext></name>
662
849
      <fsummary>Send data and binary data to port owner</fsummary>
663
850
      <desc>
664
851
        <marker id="driver_output2"></marker>
673
860
      </desc>
674
861
    </func>
675
862
    <func>
676
 
      <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char *hbuf, int hlen, ErlDrvBinary* bin, int offset, int len)</nametext></name>
 
863
      <name><ret>int</ret><nametext>driver_output_binary(ErlDrvPort port, char *hbuf, ErlDrvSizeT hlen, ErlDrvBinary* bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name>
677
864
      <fsummary>Send data from a driver binary to port owner</fsummary>
678
865
      <desc>
679
866
        <marker id="driver_output_binary"></marker>
696
883
      </desc>
697
884
    </func>
698
885
    <func>
699
 
      <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, int hlen,  ErlIOVec *ev, int skip)</nametext></name>
 
886
      <name><ret>int</ret><nametext>driver_outputv(ErlDrvPort port, char* hbuf, ErlDrvSizeT hlen,  ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name>
700
887
      <fsummary>Send vectorized data to port owner</fsummary>
701
888
      <desc>
702
889
        <marker id="driver_outputv"></marker>
719
906
      </desc>
720
907
    </func>
721
908
    <func>
722
 
      <name><ret>int</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, char *buf, int len)</nametext></name>
 
909
      <name><ret>ErlDrvSizeT</ret><nametext>driver_vec_to_buf(ErlIOVec *ev, char *buf, ErlDrvSizeT len)</nametext></name>
723
910
      <fsummary>Collect data segments into a buffer</fsummary>
724
911
      <desc>
725
912
        <marker id="driver_vec_to_buf"></marker>
746
933
          <c>time</c> parameter is the time in milliseconds before the
747
934
          timer expires.</p>
748
935
        <p>When the timer reaches 0 and expires, the driver entry
749
 
          function <seealso marker="driver_entry#emulator">timeout</seealso> is called.</p>
 
936
          function <seealso marker="driver_entry#timeout">timeout</seealso> is called.</p>
750
937
        <p>Note that there is only one timer on each driver instance;
751
938
          setting a new timer will replace an older one.</p>
752
 
        <p>Return value i 0 (-1 only when the <c>timeout</c> driver
 
939
        <p>Return value is 0 (-1 only when the <c>timeout</c> driver
753
940
          function is <c>NULL</c>).</p>
754
941
      </desc>
755
942
    </func>
799
986
          event object must be a socket or pipe (or other object that
800
987
          <c>select</c>/<c>poll</c> can use).
801
988
          On windows, the Win32 API function <c>WaitForMultipleObjects</c>
802
 
          is used. This places other restriction on the event object.
 
989
          is used. This places other restrictions on the event object.
803
990
          Refer to the Win32 SDK documentation.</p>
804
991
        <p>The <c>on</c> parameter should be <c>1</c> for setting events
805
992
          and <c>0</c> for clearing them.</p>
806
 
        <p>The <c>mode</c> argument is bitwise-or combination of
 
993
        <p>The <c>mode</c> argument is a bitwise-or combination of
807
994
          <c>ERL_DRV_READ</c>, <c>ERL_DRV_WRITE</c> and <c>ERL_DRV_USE</c>.
808
 
          The first two specifies whether to wait for read events and/or write
 
995
          The first two specify whether to wait for read events and/or write
809
996
          events. A fired read event will call
810
997
          <seealso marker="driver_entry#ready_input">ready_input</seealso>
811
998
          while a fired write event will call
812
999
          <seealso marker="driver_entry#ready_output">ready_output</seealso>.
813
1000
          </p>
814
1001
    <note>
815
 
      <p>Some OS (Windows) does not differ between read and write events.
 
1002
      <p>Some OS (Windows) do not differentiate between read and write events.
816
1003
         The call-back for a fired event then only depends on the value of <c>mode</c>.</p>
817
1004
    </note>
818
1005
        <p><c>ERL_DRV_USE</c> specifies if we are using the event object or if we want to close it.
834
1021
         as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and
835
1022
         <c>stop_select</c> to make sure that event objects are closed in a safe way.</p>
836
1023
    </note>           
837
 
        <p>The return value is 0 (Failure, -1, only if the
 
1024
        <p>The return value is 0 (failure, -1, only if the
838
1025
          <c>ready_input</c>/<c>ready_output</c> is
839
 
          <c>NULL</c>.</p>
 
1026
          <c>NULL</c>).</p>
840
1027
      </desc>
841
1028
    </func>
842
1029
    <func>
843
 
      <name><ret>void *</ret><nametext>driver_alloc(size_t size)</nametext></name>
 
1030
      <name><ret>void *</ret><nametext>driver_alloc(ErlDrvSizeT size)</nametext></name>
844
1031
      <fsummary>Allocate memory</fsummary>
845
1032
      <desc>
846
1033
        <marker id="driver_alloc"></marker>
854
1041
      </desc>
855
1042
    </func>
856
1043
    <func>
857
 
      <name><ret>void *</ret><nametext>driver_realloc(void *ptr, size_t size)</nametext></name>
 
1044
      <name><ret>void *</ret><nametext>driver_realloc(void *ptr, ErlDrvSizeT size)</nametext></name>
858
1045
      <fsummary>Resize an allocated memory block</fsummary>
859
1046
      <desc>
860
1047
        <marker id="driver_realloc"></marker>
880
1067
      </desc>
881
1068
    </func>
882
1069
    <func>
883
 
      <name><ret>ErlDrvBinary*</ret><nametext>driver_alloc_binary(int size)</nametext></name>
 
1070
      <name><ret>ErlDrvBinary*</ret><nametext>driver_alloc_binary(ErlDrvSizeT size)</nametext></name>
884
1071
      <fsummary>Allocate a driver binary</fsummary>
885
1072
      <desc>
886
1073
        <marker id="driver_alloc_binary"></marker>
900
1087
      </desc>
901
1088
    </func>
902
1089
    <func>
903
 
      <name><ret>ErlDrvBinary*</ret><nametext>driver_realloc_binary(ErlDrvBinary *bin, int size)</nametext></name>
 
1090
      <name><ret>ErlDrvBinary*</ret><nametext>driver_realloc_binary(ErlDrvBinary *bin, ErlDrvSizeT size)</nametext></name>
904
1091
      <fsummary>Resize a driver binary</fsummary>
905
1092
      <desc>
906
1093
        <marker id="driver_realloc_binary"></marker>
966
1153
      </desc>
967
1154
    </func>
968
1155
    <func>
969
 
      <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, int len)</nametext></name>
 
1156
      <name><ret>int</ret><nametext>driver_enq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name>
970
1157
      <fsummary>Enqueue data in the driver queue</fsummary>
971
1158
      <desc>
972
1159
        <marker id="driver_enq"></marker>
990
1177
      </desc>
991
1178
    </func>
992
1179
    <func>
993
 
      <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, int len)</nametext></name>
 
1180
      <name><ret>int</ret><nametext>driver_pushq(ErlDrvPort port, char* buf, ErlDrvSizeT len)</nametext></name>
994
1181
      <fsummary>Push data at the head of the driver queue</fsummary>
995
1182
      <desc>
996
1183
        <marker id="driver_pushq"></marker>
1005
1192
      </desc>
1006
1193
    </func>
1007
1194
    <func>
1008
 
      <name><ret>int</ret><nametext>driver_deq(ErlDrvPort port, int size)</nametext></name>
 
1195
      <name><ret>ErlDrvSizeT</ret><nametext>driver_deq(ErlDrvPort port, ErlDrvSizeT size)</nametext></name>
1009
1196
      <fsummary>Dequeue data from the head of the driver queue</fsummary>
1010
1197
      <desc>
1011
1198
        <marker id="driver_deq"></marker>
1021
1208
      </desc>
1022
1209
    </func>
1023
1210
    <func>
1024
 
      <name><ret>int</ret><nametext>driver_sizeq(ErlDrvPort port)</nametext></name>
 
1211
      <name><ret>ErlDrvSizeT</ret><nametext>driver_sizeq(ErlDrvPort port)</nametext></name>
1025
1212
      <fsummary>Return the size of the driver queue</fsummary>
1026
1213
      <desc>
1027
1214
        <marker id="driver_sizeq"></marker>
1034
1221
      </desc>
1035
1222
    </func>
1036
1223
    <func>
1037
 
      <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset,  int len)</nametext></name>
 
1224
      <name><ret>int</ret><nametext>driver_enq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name>
1038
1225
      <fsummary>Enqueue binary in the driver queue</fsummary>
1039
1226
      <desc>
1040
1227
        <marker id="driver_enq_bin"></marker>
1051
1238
      </desc>
1052
1239
    </func>
1053
1240
    <func>
1054
 
      <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, int offset, int len)</nametext></name>
 
1241
      <name><ret>int</ret><nametext>driver_pushq_bin(ErlDrvPort port, ErlDrvBinary *bin, ErlDrvSizeT offset, ErlDrvSizeT len)</nametext></name>
1055
1242
      <fsummary>Push binary at the head of the driver queue</fsummary>
1056
1243
      <desc>
1057
1244
        <marker id="driver_pushq_bin"></marker>
1068
1255
      </desc>
1069
1256
    </func>
1070
1257
    <func>
 
1258
      <name><ret>ErlDrvSizeT</ret><nametext>driver_peekqv(ErlDrvPort port, ErlIOVec *ev)</nametext></name>
 
1259
      <fsummary>Get the driver queue as an IO vector</fsummary>
 
1260
      <desc>
 
1261
        <marker id="driver_peekqv"></marker>
 
1262
        <p>
 
1263
          This function retrieves the driver queue into a supplied
 
1264
          <c>ErlIOVec</c> <c>ev</c>. It also returns the queue size.
 
1265
          This is one of two ways to get data out of the queue.
 
1266
        </p>
 
1267
        <p>
 
1268
          If <c>ev</c> is <c>NULL</c> all ones i.e. <c>-1</c> type cast to
 
1269
          <c>ErlDrvSizeT</c> is returned.
 
1270
        </p>
 
1271
        <p>Nothing is removed from the queue by this function, that must be done
 
1272
          with <c>driver_deq</c>.</p>
 
1273
        <p>This function can be called from an arbitrary thread if a
 
1274
          <seealso marker="#ErlDrvPDL">port data lock</seealso>
 
1275
          associated with the <c>port</c> is locked by the calling
 
1276
          thread during the call.</p>
 
1277
      </desc>
 
1278
    </func>
 
1279
    <func>
1071
1280
      <name><ret>SysIOVec*</ret><nametext>driver_peekq(ErlDrvPort port, int *vlen)</nametext></name>
1072
1281
      <fsummary>Get the driver queue as a vector</fsummary>
1073
1282
      <desc>
1074
1283
        <marker id="driver_peekq"></marker>
1075
1284
        <p>This function retrieves the driver queue as a pointer to an
1076
1285
          array of <c>SysIOVec</c>s. It also returns the number of
1077
 
          elements in <c>vlen</c>. This is the only way to get data
 
1286
          elements in <c>vlen</c>. This is one of two ways to get data
1078
1287
          out of the queue.</p>
1079
 
        <p>Nothing is remove from the queue by this function, that must be done
 
1288
        <p>Nothing is removed from the queue by this function, that must be done
1080
1289
          with <c>driver_deq</c>.</p>
1081
1290
        <p>The returned array is suitable to use with the Unix system
1082
1291
          call <c>writev</c>.</p>
1087
1296
      </desc>
1088
1297
    </func>
1089
1298
    <func>
1090
 
      <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, int skip)</nametext></name>
 
1299
      <name><ret>int</ret><nametext>driver_enqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name>
1091
1300
      <fsummary>Enqueue vector in the driver queue</fsummary>
1092
1301
      <desc>
1093
1302
        <marker id="driver_enqv"></marker>
1103
1312
      </desc>
1104
1313
    </func>
1105
1314
    <func>
1106
 
      <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec *ev, int skip)</nametext></name>
 
1315
      <name><ret>int</ret><nametext>driver_pushqv(ErlDrvPort port, ErlIOVec *ev, ErlDrvSizeT skip)</nametext></name>
1107
1316
      <fsummary>Push vector at the head of the driver queue</fsummary>
1108
1317
      <desc>
1109
1318
        <marker id="driver_pushqv"></marker>
1209
1418
      <fsummary>Stop monitoring a process from a driver</fsummary>
1210
1419
      <desc>
1211
1420
        <marker id="driver_demonitor_process"></marker>
1212
 
        <p>This function cancels an monitor created earlier. </p>
 
1421
        <p>This function cancels a monitor created earlier. </p>
1213
1422
        <p>The function returns 0 if a monitor was removed and &gt; 0
1214
1423
          if the monitor did no longer exist.</p>
1215
1424
      </desc>
1326
1535
        <p>This function signals to erlang that the driver has
1327
1536
          encountered an EOF and should be closed, unless the port was
1328
1537
          opened with the <c>eof</c> option, in that case eof is sent
1329
 
          to the port. Otherwise, the port is close and an
 
1538
          to the port. Otherwise, the port is closed and an
1330
1539
          <c>'EXIT'</c> message is sent to the port owner process.</p>
1331
1540
        <p>The return value is 0.</p>
1332
1541
      </desc>
1349
1558
          (<c>driver_failure</c>).</p>
1350
1559
        <p>The driver should fail only when in severe error situations,
1351
1560
          when the driver cannot possibly keep open, for instance
1352
 
          buffer allocation gets out of memory. Normal errors is more
1353
 
          appropriate to handle with sending error codes with
 
1561
          buffer allocation gets out of memory. For normal errors
 
1562
          it is more appropriate to send error codes with
1354
1563
          <c>driver_output</c>.</p>
1355
1564
        <p>The return value is 0.</p>
1356
1565
      </desc>
1371
1580
        <p>This function returns the process id of the process that
1372
1581
          made the current call to the driver. The process id can be
1373
1582
          used with <c>driver_send_term</c> to send back data to the
1374
 
          caller. <c>driver_caller()</c> only return valid data
 
1583
          caller. <c>driver_caller()</c> only returns valid data
1375
1584
          when currently executing in one of the following driver
1376
1585
          callbacks:</p>
1377
1586
          <taglist>
1409
1618
          tuple, the elements are given first, and then the tuple
1410
1619
          term, with a count. Likewise for lists.</p>
1411
1620
        <p>A tuple must be specified with the number of elements. (The
1412
 
          elements precedes the <c>ERL_DRV_TUPLE</c> term.)</p>
 
1621
          elements precede the <c>ERL_DRV_TUPLE</c> term.)</p>
1413
1622
        <p>A list must be specified with the number of elements,
1414
1623
          including the tail, which is the last term preceding
1415
1624
          <c>ERL_DRV_LIST</c>.</p>
1502
1711
        term encoded with the
1503
1712
        <seealso marker="erl_ext_dist">external format</seealso>,
1504
1713
        i.e., a term that has been encoded by
1505
 
        <seealso marker="erts:erlang#term_to_binary/2">erlang:term_to_binary</seealso>,
 
1714
        <seealso marker="erlang#term_to_binary/2">erlang:term_to_binary</seealso>,
1506
1715
        <seealso marker="erl_interface:ei">erl_interface</seealso>, etc.
1507
1716
        For example, if <c>binp</c> is a pointer to an <c>ErlDrvBinary</c>
1508
1717
        that contains the term <c>{17, 4711}</c> encoded with the
1518
1727
    };
1519
1728
    driver_output_term(port, spec, sizeof(spec) / sizeof(spec[0]));
1520
1729
        ]]></code>
1521
 
        <p>If you want to pass a binary and doesn't already have the content
 
1730
        <p>If you want to pass a binary and don't already have the content
1522
1731
        of the binary in an <c>ErlDrvBinary</c>, you can benefit from using
1523
1732
        <c>ERL_DRV_BUF2BINARY</c> instead of creating an <c>ErlDrvBinary</c>
1524
1733
        via <c>driver_alloc_binary()</c> and then pass the binary via
1565
1774
          <em>other</em> processes than the port owner process. The
1566
1775
          <c>receiver</c> parameter specifies the process to receive
1567
1776
          the data.</p>
1568
 
        <p>The parameters <c>term</c> and <c>n</c> does the same thing
 
1777
        <p>The parameters <c>term</c> and <c>n</c> do the same thing
1569
1778
          as in <seealso marker="#driver_output_term">driver_output_term</seealso>.</p>
1570
1779
        <p>This function is only thread-safe when the emulator with SMP
1571
1780
          support is used.</p>
1646
1855
      <fsummary>Cancel an asynchronous call</fsummary>
1647
1856
      <desc>
1648
1857
        <marker id="driver_async_cancel"></marker>
1649
 
        <p>This function cancels an asynchronous operation, by removing
1650
 
          it from the queue. Only functions in the queue can be
1651
 
          cancelled; if a function is executing, it's too late to
1652
 
          cancel it. The <c>async_free</c> function is also called.</p>
1653
 
        <p>The return value is 1 if the operation was removed from the
1654
 
          queue, otherwise 0.</p>
 
1858
        <p>This function used to cancel a scheduled asynchronous operation,
 
1859
          if it was still in the queue. It returned 1 if it succeeded, and
 
1860
          0 if it failed.</p>
 
1861
        <p>Since it could not guarantee success, it was more or less useless.
 
1862
           The user had to implement synchronization of cancellation anyway.
 
1863
           It also unnecessarily complicated the implementation. Therefore,
 
1864
           as of OTP-R15B <c>driver_async_cancel()</c> is deprecated, and
 
1865
           scheduled for removal in OTP-R16. It will currently always fail,
 
1866
           and return 0.</p>
 
1867
        <warning><p><c>driver_async_cancel()</c> is deferred and will
 
1868
                    be removed in the OTP-R16 release.</p>
 
1869
        </warning>
 
1870
 
1655
1871
      </desc>
1656
1872
    </func>
1657
1873
    <func>
1660
1876
      <desc>
1661
1877
        <marker id="driver_lock_driver"></marker>
1662
1878
        <p>This function locks the driver used by the port <c>port</c>
1663
 
          in memory for the rest of the emulator process
 
1879
          in memory for the rest of the emulator process'
1664
1880
          lifetime. After this call, the driver behaves as one of Erlang's 
1665
1881
          statically linked in drivers.</p>
1666
1882
      </desc>
1695
1911
           The driver defined handle is normally created in the
1696
1912
          <seealso marker="driver_entry#start">driver start call-back</seealso>
1697
1913
           when a port is created via
1698
 
          <seealso marker="erts:erlang#open_port/2">erlang:open_port/2</seealso>. </item>
 
1914
          <seealso marker="erlang#open_port/2">erlang:open_port/2</seealso>. </item>
1699
1915
        </taglist>
1700
1916
        <p>The caller of <c>driver_create_port()</c> is allowed to
1701
1917
          manipulate the newly created port when <c>driver_create_port()</c>
1904
2120
                 corresponding to one of the involved thread identifiers
1905
2121
                 has terminated since the thread identifier was saved,
1906
2122
                 the result of <c>erl_drv_equal_tids()</c> might not give
1907
 
                 expected result.
 
2123
                 the expected result.
1908
2124
        </p></note>
1909
2125
        <p>This function is thread-safe.</p>
1910
2126
      </desc>
2463
2679
    <title>SEE ALSO</title>
2464
2680
    <p><seealso marker="driver_entry">driver_entry(3)</seealso>,
2465
2681
      <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso>,
2466
 
      <seealso marker="erts:erlang">erlang(3)</seealso></p>
 
2682
      <seealso marker="erlang">erlang(3)</seealso></p>
2467
2683
    <p>An Alternative Distribution Driver (ERTS User's
2468
2684
      Guide Ch. 3)</p>
2469
2685
  </section>