← Back to branch summary

~ubuntu-branches/ubuntu/trusty/erlang/trusty

« back to all changes in this revision

Viewing changes to lib/kernel/doc/src/erl_ddll.xml

  • Committer: Bazaar Package Importer
  • Author(s): Clint Byrum
  • Date: 2011-05-05 15:48:43 UTC
  • mfrom: (3.5.13 sid)
  • Revision ID: james.westby@ubuntu.com-20110505154843-0om6ekzg6m7ugj27
Tags: 1:14.b.2-dfsg-3ubuntu1
* Merge from debian unstable.  Remaining changes:
  - Drop libwxgtk2.8-dev build dependency. Wx isn't in main, and not
    supposed to.
  - Drop erlang-wx binary.
  - Drop erlang-wx dependency from -megaco, -common-test, and -reltool, they
    do not really need wx. Also drop it from -debugger; the GUI needs wx,
    but it apparently has CLI bits as well, and is also needed by -megaco,
    so let's keep the package for now.
  - debian/patches/series: Do what I meant, and enable build-options.patch
    instead.
* Additional changes:
  - Drop erlang-wx from -et
* Dropped Changes:
  - patches/pcre-crash.patch: CVE-2008-2371: outer level option with
    alternatives caused crash. (Applied Upstream)
  - fix for ssl certificate verification in newSSL: 
    ssl_cacertfile_fix.patch (Applied Upstream)
  - debian/patches/series: Enable native.patch again, to get stripped beam
    files and reduce the package size again. (build-options is what
    actually accomplished this)
  - Remove build-options.patch on advice from upstream and because it caused
    odd build failures.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/kernel/doc/src/erl_ddll.xml
4
4
<erlref>
5
5
  <header>
6
6
    <copyright>
7
 
      <year>1997</year><year>2009</year>
 
7
      <year>1997</year><year>2010</year>
8
8
      <holder>Ericsson AB. All Rights Reserved.</holder>
9
9
    </copyright>
10
10
    <legalnotice>
13
13
      compliance with the License. You should have received a copy of the
14
14
      Erlang Public License along with this software. If not, it can be
15
15
      retrieved online at http://www.erlang.org/.
16
 
    
 
16
 
17
17
      Software distributed under the License is distributed on an "AS IS"
18
18
      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
      the License for the specific language governing rights and limitations
20
20
      under the License.
21
 
    
 
21
 
22
22
    </legalnotice>
23
23
 
24
24
    <title>erl_ddll</title>
177
177
      <name>demonitor(MonitorRef) -> ok</name>
178
178
      <fsummary>Remove a monitor for a driver</fsummary>
179
179
      <type>
180
 
        <v>MonitorRef = ref()</v>
 
180
        <v>MonitorRef = reference()</v>
181
181
      </type>
182
182
      <desc>
183
183
        <p>Removes a driver monitor in much the same way as 
185
185
          monitors. See <seealso marker="#monitor/2">monitor/2</seealso>, <seealso marker="#try_load/3">try_load/3</seealso> and <seealso marker="#try_unload/2">try_unload/2</seealso> for details
186
186
          about how to create driver monitors.</p>
187
187
        <p>The function throws a <c>badarg</c> exception if the
188
 
          parameter is not a ref().  </p>
 
188
          parameter is not a reference().  </p>
189
189
      </desc>
190
190
    </func>
191
191
    <func>
400
400
        <v>Item = {Name, When}</v>
401
401
        <v>Name = atom() | string()</v>
402
402
        <v>When = loaded | unloaded | unloaded_only</v>
403
 
        <v>MonitorRef = ref()</v>
 
403
        <v>MonitorRef = reference()</v>
404
404
      </type>
405
405
      <desc>
406
406
        <p>This function creates a driver monitor and works in many
449
449
                  eventually lead to one of the following messages
450
450
                  being sent:</p>
451
451
                <taglist>
452
 
                  <tag><em>{'UP', ref(), driver, Name, loaded}</em></tag>
 
452
                  <tag><em>{'UP', reference(), driver, Name, loaded}</em></tag>
453
453
                  <item>
454
454
                    <p>This message is sent, either immediately if the
455
455
                      driver is already loaded and no reloading is
459
459
                      expected to know if reloading is demanded prior
460
460
                      to creating a monitor for loading.</p>
461
461
                  </item>
462
 
                  <tag><em>{'UP', ref(), driver, Name, permanent}</em></tag>
 
462
                  <tag><em>{'UP', reference(), driver, Name, permanent}</em></tag>
463
463
                  <item>
464
464
                    <p>This message will be sent if reloading was
465
465
                      expected, but the (old) driver made itself
467
467
                      sent if the driver was permanent or statically
468
468
                      linked in when trying to create the monitor.</p>
469
469
                  </item>
470
 
                  <tag><em>{'DOWN', ref(), driver, Name, load_cancelled}</em></tag>
 
470
                  <tag><em>{'DOWN', reference(), driver, Name, load_cancelled}</em></tag>
471
471
                  <item>
472
472
                    <p>This message will arrive if reloading was
473
473
                      underway, but the <seealso marker="#users">user</seealso> having requested
476
476
                      (or <c>unload/1</c>/<c>unload_driver/1</c>)
477
477
                      again before it was reloaded.</p>
478
478
                  </item>
479
 
                  <tag><em>{'DOWN', ref(), driver, Name, {load_failure, Failure}}</em></tag>
 
479
                  <tag><em>{'DOWN', reference(), driver, Name, {load_failure, Failure}}</em></tag>
480
480
                  <item>
481
481
                    <p>This message will arrive if reloading was
482
482
                      underway but the loading for some reason
500
500
                <p>A driver monitor for unload will eventually result
501
501
                  in one of the following messages being sent:</p>
502
502
                <taglist>
503
 
                  <tag><em>{'DOWN', ref(), driver, Name, unloaded}</em></tag>
 
503
                  <tag><em>{'DOWN', reference(), driver, Name, unloaded}</em></tag>
504
504
                  <item>
505
505
                    <p>The driver instance monitored is now
506
506
                      unloaded. As the unload might have been due to a
508
508
                      again have been loaded when this message
509
509
                      arrives.</p>
510
510
                  </item>
511
 
                  <tag><em>{'UP', ref(), driver, Name, unload_cancelled}</em></tag>
 
511
                  <tag><em>{'UP', reference(), driver, Name, unload_cancelled}</em></tag>
512
512
                  <item>
513
513
                    <p>This message will be sent if unloading was
514
514
                      expected, but while the driver was waiting for
525
525
                      similar to an <c>unloaded</c> monitor, but does
526
526
                      never result in this message.</p>
527
527
                  </item>
528
 
                  <tag><em>{'UP', ref(), driver, Name, permanent}</em></tag>
 
528
                  <tag><em>{'UP', reference(), driver, Name, permanent}</em></tag>
529
529
                  <item>
530
530
                    <p>This message will be sent if unloading was
531
531
                      expected, but the driver made itself
539
539
              <item>
540
540
                <p>A monitor created as <c>unloaded_only</c> behaves
541
541
                  exactly as one created as <c>unloaded</c> with the
542
 
                  exception that the <c>{'UP', ref(), driver, Name, unload_cancelled}</c> message will never be
 
542
                  exception that the <c>{'UP', reference(), driver, Name, unload_cancelled}</c> message will never be
543
543
                  sent, but the monitor instead persists until the
544
544
                  driver <em>really</em> gets unloaded.</p>
545
545
              </item>
626
626
        <v>ReloadOption = pending_driver | pending</v>
627
627
        <v>Status = loaded | already_loaded | PendingStatus </v>
628
628
        <v>PendingStatus = pending_driver | pending_process</v>
629
 
        <v>Ref = ref()</v>
 
629
        <v>Ref = reference()</v>
630
630
        <v>ErrorDesc = ErrorAtom | OpaqueError</v>
631
631
        <v>ErrorAtom = linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded |  pending_reload | pending_process</v>
632
632
      </type>
650
650
              registered and a corresponding <c>try_unload</c> is
651
651
              expected sometime in the future.</p>
652
652
          </item>
653
 
          <tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, ref()}</em></tag>
 
653
          <tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, reference()}</em></tag>
654
654
          <item>
655
655
            <p>The load request is registered, but the loading is
656
656
              delayed due to the fact that an earlier instance of the
665
665
              set. In other words, this return value will always need
666
666
              to be handled!</p>
667
667
          </item>
668
 
          <tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, ref()}</em></tag>
 
668
          <tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, reference()}</em></tag>
669
669
          <item>
670
670
            <p>The load request is registered, but the loading is
671
671
              delayed due to the fact that an earlier instance of the
683
683
          about when the driver is <em>actually</em> loaded. This can
684
684
          be achieved by using the <c>{monitor, PendingOption}</c> option.</p>
685
685
        <p>When monitoring is requested, and a corresponding <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c> would be
686
 
          returned, the function will instead return a tuple <c>{ok, PendingStatus, ref()}</c> and the process will, at a later
 
686
          returned, the function will instead return a tuple <c>{ok, PendingStatus, reference()}</c> and the process will, at a later
687
687
          time when the driver actually gets loaded, get a monitor
688
688
          message. The monitor message one can expect is described in
689
689
          the <seealso marker="#monitor/2">monitor/2</seealso>
730
730
              extension suffix, i.e. <c>.so</c>). The name by which
731
731
              the driver identifies itself must also be consistent
732
732
              with this <c>Name</c> parameter, much as a beam-file's
733
 
              module name much correspond to it's filename.</p>
 
733
              module name much correspond to its filename.</p>
734
734
          </item>
735
735
          <tag><em>OptionList</em></tag>
736
736
          <item>
742
742
              <tag><em>{driver_options, DriverOptionsList}</em></tag>
743
743
              <item>
744
744
                <p>This option is to provide options that will change
745
 
                  it's general behavior and will "stick" to the driver
746
 
                  throughout it's lifespan.</p>
 
745
                  its general behavior and will "stick" to the driver
 
746
                  throughout its lifespan.</p>
747
747
                <p>The driver options for a given driver name need
748
748
                  always to be consistent, <em>even when the driver is reloaded</em>, meaning that they are as much a part
749
749
                  of the driver as the actual name.</p>
760
760
                <p>A <c>MonitorOption</c> tells <c>try_load/3</c> to
761
761
                  trigger a driver monitor under certain
762
762
                  conditions. When the monitor is triggered, the
763
 
                  function will return a three-tuple <c>{ok, PendingStatus, ref()}</c>, where the <c>ref()</c> is
 
763
                  function will return a three-tuple <c>{ok, PendingStatus, reference()}</c>, where the <c>reference()</c> is
764
764
                  the monitor ref for the driver monitor.</p>
765
765
                <p>Only one <c>MonitorOption</c> can be specified and
766
766
                  it is either the atom <c>pending</c>, which means
891
891
        <v>MonitorOption = pending_driver | pending</v>
892
892
        <v>Status = unloaded | PendingStatus </v>
893
893
        <v>PendingStatus = pending_driver | pending_process</v>
894
 
        <v>Ref = ref()</v>
 
894
        <v>Ref = reference()</v>
895
895
        <v>ErrorAtom = linked_in_driver | not_loaded |  not_loaded_by_this_process | permanent</v>
896
896
      </type>
897
897
      <desc>
943
943
              ports using it and there are no more <seealso marker="#users">users</seealso> requiring it to be
944
944
              loaded.</p>
945
945
          </item>
946
 
          <tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, ref()}</em></tag>
 
946
          <tag><em>{ok, pending_driver}</em>or <em>{ok, pending_driver, reference()}</em></tag>
947
947
          <item>
948
948
            <p>This return value indicates that this call removed the
949
949
              last <seealso marker="#users">user</seealso> from the
957
957
              in that case, however transient. Monitors are as always
958
958
              useful to detect when the driver is really unloaded.</p>
959
959
          </item>
960
 
          <tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, ref()}</em></tag>
 
960
          <tag><em>{ok, pending_process}</em>or <em>{ok, pending_process, reference()}</em></tag>
961
961
          <item>
962
962
            <p>The unload request is registered, but there are still
963
963
              other <seealso marker="#users">users</seealso> holding