← Back to branch summary

~statik/ubuntu/maverick/erlang/erlang-merge-testing

« back to all changes in this revision

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

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-05-01 10:14:38 UTC
  • mfrom: (3.1.4 sid)
  • Revision ID: james.westby@ubuntu.com-20090501101438-6qlr6rsdxgyzrg2z
Tags: 1:13.b-dfsg-2
* Cleaned up patches: removed unneeded patch which helped to support
  different SCTP library versions, made sure that changes for m68k
  architecture applied only when building on this architecture.
* Removed duplicated information from binary packages descriptions.
* Don't require libsctp-dev build-dependency on solaris-i386 architecture
  which allows to build Erlang on Nexenta (thanks to Tim Spriggs for
  the suggestion).

Show diffs side-by-side

added added

removed removed

Lines of Context:
erts/doc/src/erl_driver.xml
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>2001</year>
8
 
      <year>2007</year>
9
 
      <holder>Ericsson AB, All Rights Reserved</holder>
 
7
      <year>2001</year><year>2009</year>
 
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
10
9
    </copyright>
11
10
    <legalnotice>
12
 
  The contents of this file are subject to the Erlang Public License,
13
 
  Version 1.1, (the "License"); you may not use this file except in
14
 
  compliance with the License. You should have received a copy of the
15
 
  Erlang Public License along with this software. If not, it can be
16
 
  retrieved online at http://www.erlang.org/.
17
 
 
18
 
  Software distributed under the License is distributed on an "AS IS"
19
 
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
 
  the License for the specific language governing rights and limitations
21
 
  under the License.
22
 
 
23
 
  The Initial Developer of the Original Code is Ericsson AB.
 
11
      The contents of this file are subject to the Erlang Public License,
 
12
      Version 1.1, (the "License"); you may not use this file except in
 
13
      compliance with the License. You should have received a copy of the
 
14
      Erlang Public License along with this software. If not, it can be
 
15
      retrieved online at http://www.erlang.org/.
 
16
    
 
17
      Software distributed under the License is distributed on an "AS IS"
 
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
19
      the License for the specific language governing rights and limitations
 
20
      under the License.
 
21
    
24
22
    </legalnotice>
25
23
 
26
24
    <title>erl_driver</title>
298
296
        <v>int scheduler_threads</v>
299
297
      </type>
300
298
      <desc>
301
 
        <marker id="ErlDrvSysInfo"></marker>
302
299
        <p>The <c>ErlDrvSysInfo</c> structure is used for storage of
303
300
          information about the Erlang runtime system.
304
301
          <seealso marker="#driver_system_info">driver_system_info()</seealso>
325
322
          <tag>erts_version</tag>
326
323
          <item>A string containing the version number of the runtime system
327
324
           (the same as returned by
328
 
          <seealso marker="kernel:erlang#system_info_version">erlang:system_info(version)</seealso>).</item>
 
325
          <seealso marker="erts:erlang#system_info_version">erlang:system_info(version)</seealso>).</item>
329
326
          <tag>otp_release</tag>
330
327
          <item>A string containing the OTP release number
331
328
           (the same as returned by
332
 
          <seealso marker="kernel:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>).</item>
 
329
          <seealso marker="erts:erlang#system_info_otp_release">erlang:system_info(otp_release)</seealso>).</item>
333
330
          <tag>thread_support</tag>
334
331
          <item>A value <c>!= 0</c> if the runtime system has thread support;
335
332
           otherwise, <c>0</c>.</item>
346
343
          <item>The number of async threads in the async thread pool used
347
344
           by <seealso marker="#driver_async">driver_async()</seealso>
348
345
           (the same as returned by
349
 
          <seealso marker="kernel:erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>).</item>
 
346
          <seealso marker="erts:erlang#system_info_thread_pool_size">erlang:system_info(thread_pool_size)</seealso>).</item>
350
347
          <tag>scheduler_threads</tag>
351
348
          <item>The number of scheduler threads used by the runtime system
352
349
           (the same as returned by
353
 
          <seealso marker="kernel:erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>).</item>
 
350
          <seealso marker="erts:erlang#system_info_schedulers">erlang:system_info(schedulers)</seealso>).</item>
354
351
        </taglist>
355
352
      </desc>
356
353
    </func>
362
359
        <v>char orig_bytes[]</v>
363
360
      </type>
364
361
      <desc>
365
 
        <marker id="ErlDrvBinary"></marker>
366
362
        <p>The <c>ErlDrvBinary</c> structure is a binary, as sent
367
363
          between the emulator and the driver. All binaries are
368
364
          reference counted; when <c>driver_binary_free</c> is called,
412
408
      <name>ErlDrvData</name>
413
409
      <fsummary>Driver specific data</fsummary>
414
410
      <desc>
415
 
        <marker id="ErlDrvData"></marker>
416
411
        <p>The <c>ErlDrvData</c> is a handle to driver-specific data,
417
412
          passed to the driver call-backs. It is a pointer, and is
418
413
          most often casted to a specific pointer in the driver.</p>
449
444
      <name>ErlDrvMonitor</name>
450
445
      <fsummary>A monitor reference</fsummary>
451
446
      <desc>
452
 
        <marker id="ErlDrvMonitor"></marker>
453
447
        <p>When a driver creates a monitor for a process, a
454
448
          <c>ErlDrvMonitor</c> is filled in. This is an opaque
455
449
          data-type which can be assigned to but not compared without
465
459
      <name>ErlDrvNowData</name>
466
460
      <fsummary>A structure for holding timestamps</fsummary>
467
461
      <desc>
468
 
        <marker id="ErlDrvNowData"></marker>
469
462
        <p>The <c>ErlDrvNowData</c> structure holds a timestamp
470
463
          consisting of three values measured from some arbitrary
471
464
          point in the past. The three structure members are:</p>
486
479
      <name>ErlDrvPDL</name>
487
480
      <fsummary>Port Data Lock</fsummary>
488
481
      <desc>
489
 
        <marker id="ErlDrvPDL"></marker>
490
482
        <p>If certain port specific data have to be accessed from other
491
483
          threads than those calling the driver call-backs, a port data lock
492
484
          can be used in order to synchronize the operations on the data.
523
515
      <name>ErlDrvTid</name>
524
516
      <fsummary>Thread identifier</fsummary>
525
517
      <desc>
526
 
        <marker id="ErlDrvTid"></marker>
527
518
        <p>Thread identifier.</p>
528
519
        <p>See also:
529
520
           <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>,
542
533
        <v>int suggested_stack_size</v>
543
534
      </type>
544
535
      <desc>
545
 
        <marker id="ErlDrvThreadOpts"></marker>
546
536
        <p>Thread options structure passed to
547
537
           <seealso marker="#erl_drv_thread_create">erl_drv_thread_create()</seealso>.
548
538
           Currently the following fields exist:
565
555
      <name>ErlDrvMutex</name>
566
556
      <fsummary>Mutex</fsummary>
567
557
      <desc>
568
 
        <marker id="ErlDrvMutex"></marker>
569
558
        <p>Mutual exclusion lock. Used for synchronizing access to shared data.
570
559
           Only one thread at a time can lock a mutex.
571
560
        </p>
583
572
      <name>ErlDrvCond</name>
584
573
      <fsummary>Condition variable</fsummary>
585
574
      <desc>
586
 
        <marker id="ErlDrvCond"></marker>
587
575
        <p>Condition variable. Used when threads need to wait for a specific
588
576
           condition to appear before continuing execution. Condition variables
589
577
           need to be used with associated mutexes.
602
590
      <name>ErlDrvRWLock</name>
603
591
      <fsummary>Rwlock</fsummary>
604
592
      <desc>
605
 
        <marker id="ErlDrvRWLock"></marker>
606
593
        <p>Read/write lock. Used to allow multiple threads to read shared data
607
594
           while only allowing one thread to write the same data. Multiple threads
608
595
           can read lock an rwlock at the same time, while only one thread can
625
612
      <name>ErlDrvTSDKey</name>
626
613
      <fsummary>Thread specific data key</fsummary>
627
614
      <desc>
628
 
        <marker id="ErlDrvTSDKey"></marker>
629
615
        <p>Key which thread specific data can be associated with.</p>
630
616
        <p>See also:
631
617
           <seealso marker="#erl_drv_tsd_key_create">erl_drv_tsd_key_create()</seealso>,
807
793
      <fsummary>Provide an event for having the emulator call the driver</fsummary>
808
794
      <desc>
809
795
        <marker id="driver_select"></marker>
810
 
        <p>The <c>driver_select</c> is used by the driver to
811
 
          provide the emulator with an event to check for. This
812
 
          enables the emulator to call the driver when something has
813
 
          happened asynchronously.</p>
814
 
        <p>The <c>event</c> parameter is used in the emulator cycle in
815
 
          a <c>select</c> call. If the event is set then the driver is
816
 
          called. The <c>mode</c> parameter can be either
817
 
          <c>ON_READ</c> or <c>ON_WRITE</c>, and specifies whether
818
 
          <seealso marker="driver_entry#ready_output">ready_output</seealso>
819
 
          or <seealso marker="driver_entry#ready_input">ready_input</seealso>
820
 
          will be called when the event is fired. Note that this is
821
 
          just a convention, they don't have to read or write
822
 
          anything.</p>
823
 
        <p>The <c>on</c> parameter should be <c>1</c> for adding the
824
 
          event and <c>0</c> for removing it.</p>
825
 
        <p>On Unix systems, the function <c>select</c> is used. The
826
 
          <c>event</c> must be a socket or pipe (or other object that
827
 
          <c>select</c> can use).</p>
828
 
        <p>On windows, the Win32 API function
829
 
          <c>WaitForMultipleObjects</c> is used. This places other
830
 
          restriction on the <c>event</c>. Refer to the Win32 SDK
831
 
          documentation.</p>
 
796
        <p>This function is used by drivers to provide the emulator with
 
797
          events to check for. This enables the emulator to call the driver
 
798
          when something has happened asynchronously.</p>
 
799
        <p>The <c>event</c> argument indentifies an OS-specific event object.
 
800
          On Unix systems, the functions <c>select</c>/<c>poll</c> are used. The
 
801
          event object must be a socket or pipe (or other object that
 
802
          <c>select</c>/<c>poll</c> can use).
 
803
          On windows, the Win32 API function <c>WaitForMultipleObjects</c>
 
804
          is used. This places other restriction on the event object.
 
805
          Refer to the Win32 SDK documentation.</p>
 
806
        <p>The <c>on</c> parameter should be <c>1</c> for setting events
 
807
          and <c>0</c> for clearing them.</p>
 
808
        <p>The <c>mode</c> argument is bitwise-or combination of
 
809
          <c>ERL_DRV_READ</c>, <c>ERL_DRV_WRITE</c> and <c>ERL_DRV_USE</c>.
 
810
          The first two specifies whether to wait for read events and/or write
 
811
          events. A fired read event will call
 
812
          <seealso marker="driver_entry#ready_input">ready_input</seealso>
 
813
          while a fired write event will call
 
814
          <seealso marker="driver_entry#ready_output">ready_output</seealso>.
 
815
          </p>
 
816
    <note>
 
817
      <p>Some OS (Windows) does not differ between read and write events.
 
818
         The call-back for a fired event then only depends on the value of <c>mode</c>.</p>
 
819
    </note>
 
820
        <p><c>ERL_DRV_USE</c> specifies if we are using the event object or if we want to close it.
 
821
           On an emulator with SMP support, it is not safe to clear all events
 
822
           and then close the event object after <c>driver_select</c> has
 
823
           returned. Another thread may still be using the event object
 
824
           internally. To safely close an event object call
 
825
           <c>driver_select</c> with <c>ERL_DRV_USE</c> and <c>on==0</c>. That
 
826
           will clear all events and then call 
 
827
           <seealso marker="driver_entry#stop_select">stop_select</seealso>
 
828
           when it is safe to close the event object.
 
829
           <c>ERL_DRV_USE</c> should be set together with the first event
 
830
           for an event object. It is harmless to set <c>ERL_DRV_USE</c>
 
831
           even though it already has been done. Clearing all events but keeping
 
832
           <c>ERL_DRV_USE</c> set will indicate that we are using the event
 
833
           object and probably will set events for it again.</p>
 
834
    <note>
 
835
      <p>ERL_DRV_USE was added in OTP release R13. Old drivers will still work
 
836
         as before. But it is recommended to update them to use <c>ERL_DRV_USE</c> and
 
837
         <c>stop_select</c> to make sure that event objects are closed in a safe way.</p>
 
838
    </note>           
832
839
        <p>The return value is 0 (Failure, -1, only if the
833
840
          <c>ready_input</c>/<c>ready_output</c> is
834
841
          <c>NULL</c>.</p>
1007
1014
        <p>This function dequeues data by moving the head pointer
1008
1015
          forward in the driver queue by <c>size</c> bytes. The data
1009
1016
          in the queue will be dealloced.</p>
1010
 
        <p>The return value is 0.</p>
 
1017
        <p>The return value is the number of bytes remaining in the queue
 
1018
          or -1 on failure.</p>
1011
1019
        <p>This function can be called from an arbitrary thread if a
1012
1020
          <seealso marker="#ErlDrvPDL">port data lock</seealso>
1013
1021
          associated with the <c>port</c> is locked by the calling
1479
1487
        term encoded with the
1480
1488
        <seealso marker="erl_ext_dist">external format</seealso>,
1481
1489
        i.e., a term that has been encoded by
1482
 
        <seealso marker="kernel:erlang#term_to_binary/2">erlang:term_to_binary</seealso>,
 
1490
        <seealso marker="erts:erlang#term_to_binary/2">erlang:term_to_binary</seealso>,
1483
1491
        <seealso marker="erl_interface:ei">erl_interface</seealso>, etc.
1484
1492
        For example, if <c>binp</c> is a pointer to an <c>ErlDrvBinary</c>
1485
1493
        that contains the term <c>{17, 4711}</c> encoded with the
1672
1680
           The driver defined handle is normally created in the
1673
1681
          <seealso marker="driver_entry#start">driver start call-back</seealso>
1674
1682
           when a port is created via
1675
 
          <seealso marker="kernel:erlang#open_port/2">erlang:open_port/2</seealso>. </item>
 
1683
          <seealso marker="erts:erlang#open_port/2">erlang:open_port/2</seealso>. </item>
1676
1684
        </taglist>
1677
1685
        <p>The caller of <c>driver_create_port()</c> is allowed to
1678
1686
          manipulate the newly created port when <c>driver_create_port()</c>
2440
2448
    <title>SEE ALSO</title>
2441
2449
    <p><seealso marker="driver_entry">driver_entry(3)</seealso>,
2442
2450
      <seealso marker="kernel:erl_ddll">erl_ddll(3)</seealso>,
2443
 
      <seealso marker="kernel:erlang">erlang(3)</seealso></p>
 
2451
      <seealso marker="erts:erlang">erlang(3)</seealso></p>
2444
2452
    <p>An Alternative Distribution Driver (ERTS User's
2445
2453
      Guide Ch. 3)</p>
2446
2454
  </section>