1erl_ddll(3)                Erlang Module Definition                erl_ddll(3)
2
3
4

NAME

6       erl_ddll - Dynamic driver loader and linker.
7

DESCRIPTION

9       This  module  provides  an  interface  for loading and unloading Erlang
10       linked-in drivers in runtime.
11
12   Note:
13       This is a large reference document. For casual use of this module,  and
14       for  most real world applications, the descriptions of functions load/2
15       and unload/1 are enough to getting started.
16
17
18       The driver is to be provided as a  dynamically  linked  library  in  an
19       object code format specific for the platform in use, that is, .so files
20       on most Unix systems and .ddl files on  Windows.  An  Erlang  linked-in
21       driver must provide specific interfaces to the emulator, so this module
22       is not designed for  loading  arbitrary  dynamic  libraries.  For  more
23       information about Erlang drivers, see erts:erl_driver .
24
25       When describing a set of functions (that is, a module, a part of a mod‐
26       ule, or an application), executing in a process and wanting  to  use  a
27       ddll-driver,  we use the term user. A process can have many users (dif‐
28       ferent modules needing the same driver) and many processes running  the
29       same code, making up many users of a driver.
30
31       In  the  basic  scenario, each user loads the driver before starting to
32       use it and unloads the driver when done. The reference  counting  keeps
33       track  of  processes  and the number of loads by each process. This way
34       the driver is only unloaded when no one wants it (it has no user).  The
35       driver  also  keeps  track of ports that are opened to it. This enables
36       delay of unloading until all ports are closed, or killing of all  ports
37       that use the driver when it is unloaded.
38
39       The  interface  supports  two basic scenarios of loading and unloading.
40       Each scenario can also have the option of either killing ports when the
41       driver  is unloading, or waiting for the ports to close themselves. The
42       scenarios are as follows:
43
44         Load and Unload on a "When Needed Basis":
45           This (most common) scenario simply supports that each user  of  the
46           driver  loads  it when needed and unloads it when no longer needed.
47           The driver is always reference counted and as  long  as  a  process
48           keeping  the driver loaded is still alive, the driver is present in
49           the system.
50
51           Each user of the driver use literally the  same  pathname  for  the
52           driver when demanding load, but the users are not concerned with if
53           the driver is already loaded from the file system or if the  object
54           code must be loaded from file system.
55
56           The following two pairs of functions support this scenario:
57
58           load/2 and unload/1:
59             When using the load/unload interfaces, the driver is not unloaded
60             until the last port using the driver is closed. Function unload/1
61             can  return  immediately,  as the users have no interrest in when
62             the unloading occurs. The driver is unloaded when no one needs it
63             any longer.
64
65             If  a  process  having  the  driver  loaded dies, it has the same
66             effect as if unloading is done.
67
68             When loading, function load/2 returns ok when any instance of the
69             driver  is  present. Thus, if a driver is waiting to get unloaded
70             (because of open ports), it simply changes  state  to  no  longer
71             need unloading.
72
73           load_driver/2 and unload_driver/1:
74             These interfaces are intended to be used when it is considered an
75             error that ports are open to a driver that no  user  has  loaded.
76             The   ports  that  are  still  open  when  the  last  user  calls
77             unload_driver/1 or when the last process having the driver loaded
78             dies, are killed with reason driver_unloaded.
79
80             The  function  names  load_driver  and unload_driver are kept for
81             backward compatibility.
82
83         Loading and Reloading for Code Replacement:
84           This scenario can occur if the driver code needs replacement during
85           operation of the Erlang emulator. Implementing driver code replace‐
86           ment is a little more tedious than Beam code  replacement,  as  one
87           driver  cannot be loaded as both "old" and "new" code. All users of
88           a driver must have it closed (no open ports) before  the  old  code
89           can be unloaded and the new code can be loaded.
90
91           The unloading/loading is done as one atomic operation, blocking all
92           processes in the system from using the driver in question while  in
93           progress.
94
95           The  preferred way to do driver code replacement is to let one sin‐
96           gle process keep track of the driver. When the process starts,  the
97           driver  is  loaded.  When  replacement  is  required, the driver is
98           reloaded. Unload is probably never done, or done when  the  process
99           exits. If more than one user has a driver loaded when code replace‐
100           ment is demanded, the  replacement  cannot  occur  until  the  last
101           "other" user has unloaded the driver.
102
103           Demanding  reload when a reload is already in progress is always an
104           error. Using the high-level functions,  it  is  also  an  error  to
105           demand reloading when more than one user has the driver loaded.
106
107           To simplify driver replacement, avoid designing your system so that
108           more than one user has the driver loaded.
109
110           The two functions for reloading drivers are  to  be  used  together
111           with  corresponding  load  functions  to  support the two different
112           behaviors concerning open ports:
113
114           load/2 and reload/2:
115             This pair of functions is used when reloading is to be done after
116             the last open port to the driver is closed.
117
118             As  reload/2  waits  for  the  reloading  to occur, a misbehaving
119             process keeping open ports to the driver (or keeping  the  driver
120             loaded)  can cause infinite waiting for reload. Time-outs must be
121             provided outside of the process demanding the reload or by  using
122             the  low-level  interface  try_load/3  in combination with driver
123             monitors.
124
125           load_driver/2 and reload_driver/2:
126             This pair of functions are used when open ports to the driver are
127             to  be killed with reason driver_unloaded to allow for new driver
128             code to get loaded.
129
130             However, if  another  process  has  the  driver  loaded,  calling
131             reload_driver  returns error code pending_process. As stated ear‐
132             lier, the recommended design is to not allow other users than the
133             "driver reloader" to demand loading of the driver in question.
134

DATA TYPES

136       driver() = iolist() | atom()
137
138       path() = string() | atom()
139

EXPORTS

141       demonitor(MonitorRef) -> ok
142
143              Types:
144
145                 MonitorRef = reference()
146
147              Removes  a driver monitor in much the same way as erlang:demoni‐
148              tor/1 in ERTS does with process monitors. For details about  how
149              to  create  driver  monitors,  see  monitor/2,  try_load/3,  and
150              try_unload/2.
151
152              The function throws a badarg exception if the parameter is not a
153              reference().
154
155       format_error(ErrorDesc) -> string()
156
157              Types:
158
159                 ErrorDesc = term()
160
161              Takes an ErrorDesc returned by load, unload, or reload functions
162              and returns a string that describes the error or warning.
163
164          Note:
165              Because of peculiarities in the dynamic  loading  interfaces  on
166              different  platforms,  the returned string is only guaranteed to
167              describe the correct error if format_error/1 is  called  in  the
168              same  instance  of  the  Erlang  virtual  machine  as  the error
169              appeared in (meaning the same operating system process).
170
171
172       info() -> AllInfoList
173
174              Types:
175
176                 AllInfoList = [DriverInfo]
177                 DriverInfo = {DriverName, InfoList}
178                 DriverName = string()
179                 InfoList = [InfoItem]
180                 InfoItem = {Tag :: atom(), Value :: term()}
181
182              Returns a list of tuples {DriverName, InfoList}, where  InfoList
183              is the result of calling info/1 for that DriverName. Only dynam‐
184              ically linked-in drivers are included in the list.
185
186       info(Name) -> InfoList
187
188              Types:
189
190                 Name = driver()
191                 InfoList = [InfoItem, ...]
192                 InfoItem = {Tag :: atom(), Value :: term()}
193
194              Returns a list of tuples {Tag, Value}, where Tag is the informa‐
195              tion  item  and  Value is the result of calling info/2 with this
196              driver name and this tag. The result is a tuple list  containing
197              all information available about a driver.
198
199              The following tags appears in the list:
200
201                * processes
202
203                * driver_options
204
205                * port_count
206
207                * linked_in_driver
208
209                * permanent
210
211                * awaiting_load
212
213                * awaiting_unload
214
215              For a detailed description of each value, see info/2.
216
217              The  function  throws  a  badarg  exception if the driver is not
218              present in the system.
219
220       info(Name, Tag) -> Value
221
222              Types:
223
224                 Name = driver()
225                 Tag =
226                     processes |
227                     driver_options |
228                     port_count |
229                     linked_in_driver |
230                     permanent |
231                     awaiting_load |
232                     awaiting_unload
233                 Value = term()
234
235              Returns specific information  about  one  aspect  of  a  driver.
236              Parameter  Tag  specifies which aspect to get information about.
237              The return Value differs between different tags:
238
239                processes:
240                  Returns all processes containing users of the specific driv‐
241                  ers  as a list of tuples {pid(),integer() >= 0}, where inte‐
242                  ger() denotes the number of users in process pid().
243
244                driver_options:
245                  Returns a list of the driver options provided when  loading,
246                  and any options set by the driver during initialization. The
247                  only valid option is kill_ports.
248
249                port_count:
250                  Returns the number of ports (an integer() >=  0)  using  the
251                  driver.
252
253                linked_in_driver:
254                  Returns a boolean(), which is true if the driver is a stati‐
255                  cally linked-in one, otherwise false.
256
257                permanent:
258                  Returns a boolean(), which is true if the  driver  has  made
259                  itself permanent (and is not a statically linked-in driver),
260                  otherwise false.
261
262                awaiting_load:
263                  Returns a list of all processes having monitors for  loading
264                  active.  Each process is returned as {pid(),integer() >= 0},
265                  where integer() is the number of monitors  held  by  process
266                  pid().
267
268                awaiting_unload:
269                  Returns  a list of all processes having monitors for unload‐
270                  ing active. Each process is returned as {pid(),integer()  >=
271                  0},  where  integer()  is  the  number  of  monitors held by
272                  process pid().
273
274              If option linked_in_driver or permanent returns true, all  other
275              options return linked_in_driver or permanent, respectively.
276
277              The  function  throws  a  badarg  exception if the driver is not
278              present in the system or if the tag is not supported.
279
280       load(Path, Name) -> ok | {error, ErrorDesc}
281
282              Types:
283
284                 Path = path()
285                 Name = driver()
286                 ErrorDesc = term()
287
288              Loads and links the dynamic driver Name. Path is a file path  to
289              the  directory  containing  the  driver. Name must be a sharable
290              object/dynamic library. Two drivers with different Path  parame‐
291              ters  cannot  be loaded under the same name. Name is a string or
292              atom containing at least one character.
293
294              The Name specified is to  correspond  to  the  filename  of  the
295              dynamically loadable object file residing in the directory spec‐
296              ified as Path, but without the extension  (that  is,  .so).  The
297              driver  name  provided in the driver initialization routine must
298              correspond with the filename, in much the  same  way  as  Erlang
299              module names correspond to the names of the .beam files.
300
301              If  the  driver  was  previously  unloaded, but is still present
302              because of open ports to it, a call to load/2 stops the  unload‐
303              ing  and  keeps the driver (as long as Path is the same), and ok
304              is returned. If you really want the object code to be  reloaded,
305              use  reload/2 or the low-level interface try_load/3 instead. See
306              also the description of different scenarios for  loading/unload‐
307              ing in the introduction.
308
309              If  more than one process tries to load an already loaded driver
310              with the same Path, or if the same process tries to load it many
311              times,  the function returns ok. The emulator keeps track of the
312              load/2 calls, so that a corresponding number of  unload/2  calls
313              must  be  done  from  the  same  process  before the driver gets
314              unloaded. It is therefore safe for  an  application  to  load  a
315              driver  that  is  shared  between processes or applications when
316              needed. It can safely be unloaded without  causing  trouble  for
317              other parts of the system.
318
319              It  is  not  allowed to load multiple drivers with the same name
320              but with different Path parameters.
321
322          Note:
323              Path is interpreted literally, so that all loaders of  the  same
324              driver  must specify the same literal Path string, although dif‐
325              ferent paths can point out the same directory in the file system
326              (because of use of relative paths and links).
327
328
329              On  success,  the  function  returns  ok. On failure, the return
330              value is {error,ErrorDesc}, where ErrorDesc is an opaque term to
331              be   translated  into  human  readable  form  by  function  for‐
332              mat_error/1.
333
334              For more control over the error  handling,  use  the  try_load/3
335              interface instead.
336
337              The function throws a badarg exception if the parameters are not
338              specified as described here.
339
340       load_driver(Path, Name) -> ok | {error, ErrorDesc}
341
342              Types:
343
344                 Path = path()
345                 Name = driver()
346                 ErrorDesc = term()
347
348              Works essentially as load/2, but loads  the  driver  with  other
349              options.  All  ports  using  the  driver  are killed with reason
350              driver_unloaded when the driver is to be unloaded.
351
352              The number of loads and unloads by  different  users  influences
353              the  loading  and  unloading  of a driver file. The port killing
354              therefore only occurs when the last user unloads the driver,  or
355              when the last process having loaded the driver exits.
356
357              This  interface  (or at least the name of the functions) is kept
358              for    backward    compatibility.    Using    try_load/3    with
359              {driver_options,[kill_ports]}  in the option list gives the same
360              effect regarding the port killing.
361
362              The function throws a badarg exception if the parameters are not
363              specified as described here.
364
365       loaded_drivers() -> {ok, Drivers}
366
367              Types:
368
369                 Drivers = [Driver]
370                 Driver = string()
371
372              Returns  a  list of all the available drivers, both (statically)
373              linked-in and dynamically loaded ones.
374
375              The driver names are returned as a list of strings rather than a
376              list of atoms for historical reasons.
377
378              For more information about drivers, see info.
379
380       monitor(Tag, Item) -> MonitorRef
381
382              Types:
383
384                 Tag = driver
385                 Item = {Name, When}
386                 Name = driver()
387                 When = loaded | unloaded | unloaded_only
388                 MonitorRef = reference()
389
390              Creates  a driver monitor and works in many ways as erlang:moni‐
391              tor/2 in ERTS, does for processes. When a driver changes  state,
392              the  monitor  results  in  a monitor message that is sent to the
393              calling  process.  MonitorRef  returned  by  this  function   is
394              included in the message sent.
395
396              As with process monitors, each driver monitor set only generates
397              one single message. The monitor is "destroyed" after the message
398              is sent, so it is then not needed to call demonitor/1.
399
400              MonitorRef  can  also be used in subsequent calls to demonitor/1
401              to remove a monitor.
402
403              The function accepts the following parameters:
404
405                Tag:
406                  The monitor tag is always driver, as this function can  only
407                  be  used  to  create  driver monitors. In the future, driver
408                  monitors will be integrated with process monitors, why  this
409                  parameter has to be specified for consistence.
410
411                Item:
412                  Parameter Item specifies which driver to monitor (the driver
413                  name) and which state change to monitor. The parameter is  a
414                  tuple  of  arity  two whose first element is the driver name
415                  and second element is one of the following:
416
417                  loaded:
418                    Notifies when the driver is reloaded (or loaded if loading
419                    is  underway). It only makes sense to monitor drivers that
420                    are in the process of being loaded or reloaded.  A  future
421                    driver  name  for  loading  cannot be monitored. That only
422                    results in a DOWN message sent immediately. Monitoring for
423                    loading  is  therefore most useful when triggered by func‐
424                    tion try_load/3, where the monitor is created because  the
425                    driver is in such a pending state.
426
427                    Setting  a  driver monitor for loading eventually leads to
428                    one of the following messages being sent:
429
430                    {'UP', reference(), driver, Name, loaded}:
431                      This message is sent either immediately if the driver is
432                      already  loaded  and  no  reloading  is pending, or when
433                      reloading is executed if reloading is pending.
434
435                      The user is expected to know if  reloading  is  demanded
436                      before creating a monitor for loading.
437
438                    {'UP', reference(), driver, Name, permanent}:
439                      This  message is sent if reloading was expected, but the
440                      (old) driver made itself permanent before reloading.  It
441                      is  also  sent if the driver was permanent or statically
442                      linked-in when trying to create the monitor.
443
444                    {'DOWN', reference(), driver, Name, load_cancelled}:
445                      This message arrives if reloading was underway, but  the
446                      requesting   user  cancelled  it  by  dying  or  calling
447                      try_unload/2 (or unload/1/unload_driver/1) again  before
448                      it was reloaded.
449
450                    {'DOWN',  reference(),  driver, Name, {load_failure, Fail‐
451                    ure}}:
452                      This message arrives if reloading was underway  but  the
453                      loading  for some reason failed. The Failure term is one
454                      of the errors that can be returned from try_load/3.  The
455                      error  term can be passed to format_error/1 for transla‐
456                      tion into human readable form. Notice that the  transla‐
457                      tion  must  be  done  in the same running Erlang virtual
458                      machine as the error was detected in.
459
460                  unloaded:
461                    Monitors when a driver gets unloaded. If  one  monitors  a
462                    driver  that is not present in the system, one immediately
463                    gets notified that the driver got unloaded.  There  is  no
464                    guarantee that the driver was ever loaded.
465
466                    A  driver  monitor for unload eventually results in one of
467                    the following messages being sent:
468
469                    {'DOWN', reference(), driver, Name, unloaded}:
470                      The monitored driver instance is now  unloaded.  As  the
471                      unload can be a result of a reload/2 request, the driver
472                      can once  again  have  been  loaded  when  this  message
473                      arrives.
474
475                    {'UP', reference(), driver, Name, unload_cancelled}:
476                      This  message  is  sent  if  unloading was expected, but
477                      while the driver  was  waiting  for  all  ports  to  get
478                      closed,  a  new  user  of  the  driver appeared, and the
479                      unloading was cancelled.
480
481                      This  message  appears  if  {ok,   pending_driver}   was
482                      returned  from  try_unload/2  for  the  last user of the
483                      driver, and then {ok, already_loaded} is returned from a
484                      call to try_load/3.
485
486                      If  one  really  wants  to  monitor when the driver gets
487                      unloaded, this message distorts the picture, because  no
488                      unloading was done. Option unloaded_only creates a moni‐
489                      tor similar to an unloaded monitor, but never results in
490                      this message.
491
492                    {'UP', reference(), driver, Name, permanent}:
493                      This  message is sent if unloading was expected, but the
494                      driver made itself permanent  before  unloading.  It  is
495                      also sent if trying to monitor a permanent or statically
496                      linked-in driver.
497
498                  unloaded_only:
499                    A monitor created as unloaded_only behaves exactly as  one
500                    created  as  unloaded  except that the {'UP', reference(),
501                    driver, Name, unload_cancelled} message is never sent, but
502                    the  monitor instead persists until the driver really gets
503                    unloaded.
504
505              The function throws a badarg exception if the parameters are not
506              specified as described here.
507
508       reload(Path, Name) -> ok | {error, ErrorDesc}
509
510              Types:
511
512                 Path = path()
513                 Name = driver()
514                 ErrorDesc = pending_process | OpaqueError
515                 OpaqueError = term()
516
517              Reloads  the  driver  named  Name from a possibly different Path
518              than previously used. This function is used in the  code  change
519              scenario described in the introduction.
520
521              If  there  are  other users of this driver, the function returns
522              {error, pending_process}, but if there are no other  users,  the
523              function call hangs until all open ports are closed.
524
525          Note:
526              Avoid mixing multiple users with driver reload requests.
527
528
529              To avoid hanging on open ports, use function try_load/3 instead.
530
531              The  Name  and  Path parameters have exactly the same meaning as
532              when calling the plain function load/2.
533
534              On success, the function returns ok. On  failure,  the  function
535              returns  an  opaque  error,  except  the  pending_process  error
536              described earlier. The opaque errors are to be  translated  into
537              human readable form by function format_error/1.
538
539              For  more  control  over  the error handling, use the try_load/3
540              interface instead.
541
542              The function throws a badarg exception if the parameters are not
543              specified as described here.
544
545       reload_driver(Path, Name) -> ok | {error, ErrorDesc}
546
547              Types:
548
549                 Path = path()
550                 Name = driver()
551                 ErrorDesc = pending_process | OpaqueError
552                 OpaqueError = term()
553
554              Works  exactly  as  reload/2,  but  for  drivers loaded with the
555              load_driver/2 interface.
556
557              As this interface implies that ports are killed  when  the  last
558              user disappears, the function does not hang waiting for ports to
559              get closed.
560
561              For more details, see scenarios in this module  description  and
562              the function description for reload/2.
563
564              The function throws a badarg exception if the parameters are not
565              specified as described here.
566
567       try_load(Path, Name, OptionList) ->
568                   {ok, Status} |
569                   {ok, PendingStatus, Ref} |
570                   {error, ErrorDesc}
571
572              Types:
573
574                 Path = path()
575                 Name = driver()
576                 OptionList = [Option]
577                 Option =
578                     {driver_options, DriverOptionList} |
579                     {monitor, MonitorOption} |
580                     {reload, ReloadOption}
581                 DriverOptionList = [DriverOption]
582                 DriverOption = kill_ports
583                 MonitorOption = ReloadOption = pending_driver | pending
584                 Status = loaded | already_loaded | PendingStatus
585                 PendingStatus = pending_driver | pending_process
586                 Ref = reference()
587                 ErrorDesc = ErrorAtom | OpaqueError
588                 ErrorAtom =
589                     linked_in_driver |
590                     inconsistent |
591                     permanent |
592                     not_loaded_by_this_process |
593                     not_loaded |
594                     pending_reload |
595                     pending_process
596                 OpaqueError = term()
597
598              Provides   more   control   than   the    load/2/reload/2    and
599              load_driver/2/reload_driver/2  interfaces.  It  never  waits for
600              completion of other operations related to the driver, but  imme‐
601              diately  returns  the status of the driver as one of the follow‐
602              ing:
603
604                {ok, loaded}:
605                  The driver was loaded and is immediately usable.
606
607                {ok, already_loaded}:
608                  The driver was already loaded by another process  or  is  in
609                  use by a living port, or both. The load by you is registered
610                  and a corresponding try_unload is expected sometime  in  the
611                  future.
612
613                {ok, pending_driver}or {ok, pending_driver, reference()}:
614                  The  load  request is registered, but the loading is delayed
615                  because an earlier instance of the driver is  still  waiting
616                  to  get  unloaded  (open  ports  use  it).  Still, unload is
617                  expected when you are done  with  the  driver.  This  return
618                  value  mostly occurs when options {reload,pending_driver} or
619                  {reload,pending} are used, but can occur when  another  user
620                  is   unloading  a  driver  in  parallel  and  driver  option
621                  kill_ports is set. In other words, this return value  always
622                  needs to be handled.
623
624                {ok, pending_process}or {ok, pending_process, reference()}:
625                  The  load  request is registered, but the loading is delayed
626                  because an earlier instance of the driver is  still  waiting
627                  to  get  unloaded  by  another  user (not only by a port, in
628                  which case {ok,pending_driver} would  have  been  returned).
629                  Still, unload is expected when you are done with the driver.
630                  This return value only occurs when  option  {reload,pending}
631                  is used.
632
633              When  the  function  returns  {ok, pending_driver} or {ok, pend‐
634              ing_process}, one can get information about when the  driver  is
635              actually loaded by using option {monitor, MonitorOption}.
636
637              When  monitoring  is  requested,  and a corresponding {ok, pend‐
638              ing_driver} or {ok,  pending_process}  would  be  returned,  the
639              function  instead  returns  a  tuple  {ok, PendingStatus, refer‐
640              ence()} and the process then gets a monitor message later,  when
641              the  driver  gets  loaded.  The  monitor  message  to  expect is
642              described in the function description of monitor/2.
643
644          Note:
645              In case of loading, monitoring can not  only  get  triggered  by
646              using  option  {reload, ReloadOption}, but also in special cases
647              where  the  load  error  is  transient.  Thus,  {monitor,  pend‐
648              ing_driver} is to be used under basically all real world circum‐
649              stances.
650
651
652              The function accepts the following parameters:
653
654                Path:
655                  The file system path  to  the  directory  where  the  driver
656                  object  file  is  located.  The  filename of the object file
657                  (minus extension) must correspond to the driver  name  (used
658                  in  parameter Name) and the driver must identify itself with
659                  the same name. Path can be provided as an iolist(),  meaning
660                  it can be a list of other iolist()s, characters (8-bit inte‐
661                  gers), or binaries, all to be flattened into a  sequence  of
662                  characters.
663
664                  The  (possibly  flattened) Path parameter must be consistent
665                  throughout the system. A driver is  to,  by  all  users,  be
666                  loaded  using  the  same literal Path. The exception is when
667                  reloading is requested, in which case Path can be  specified
668                  differently. Notice that all users trying to load the driver
669                  later need to use the new Path if Path is  changed  using  a
670                  reload  option.  This is yet another reason to have only one
671                  loader of a driver one wants to upgrade in a running system.
672
673                Name:
674                  This parameter is the name of the driver to be used in  sub‐
675                  sequent calls to function erlang:open_port in ERTS. The name
676                  can be specified as an iolist() or an atom(). The name spec‐
677                  ified when loading is used to find the object file (with the
678                  help of Path and the system-implied extension  suffix,  that
679                  is,  .so).  The  name  by which the driver identifies itself
680                  must also be consistent with this Name  parameter,  much  as
681                  the module name of a Beam file much corresponds to its file‐
682                  name.
683
684                OptionList:
685                  Some options can be specified to control the loading  opera‐
686                  tion. The options are specified as a list of two-tuples. The
687                  tuples have the following values and meanings:
688
689                  {driver_options, DriverOptionList}:
690                    This is to provide options that changes its general behav‐
691                    ior and "sticks" to the driver throughout its lifespan.
692
693                    The driver options for a specified driver name need always
694                    to be consistent, even when the driver is reloaded,  mean‐
695                    ing  that  they  are  as  much a part of the driver as the
696                    name.
697
698                    The only allowed driver option is kill_ports, which  means
699                    that  all  ports opened to the driver are killed with exit
700                    reason driver_unloaded when no process any longer has  the
701                    driver  loaded. This situation arises either when the last
702                    user calls try_unload/2, or when the last  process  having
703                    loaded the driver exits.
704
705                  {monitor, MonitorOption}:
706                    A MonitorOption tells try_load/3 to trigger a driver moni‐
707                    tor under certain conditions. When the  monitor  is  trig‐
708                    gered, the function returns a three-tuple {ok, PendingSta‐
709                    tus, reference()}, where reference() is the monitor refer‐
710                    ence for the driver monitor.
711
712                    Only  one MonitorOption can be specified. It is one of the
713                    following:
714
715                    * The atom pending, which means that a monitor  is  to  be
716                      created whenever a load operation is delayed,
717
718                    * The  atom  pending_driver, in which a monitor is created
719                      whenever the operation is delayed because of open  ports
720                      to an otherwise unused driver.
721
722                    Option pending_driver is of little use, but is present for
723                    completeness, as it is well defined which  reload  options
724                    that  can  give rise to which delays. However, it can be a
725                    good idea to use the same MonitorOption as  the  ReloadOp‐
726                    tion, if present.
727
728                    If  reloading  is not requested, it can still be useful to
729                    specify option monitor, as forced unloads  (driver  option
730                    kill_ports or option kill_ports to try_unload/2) trigger a
731                    transient state where driver loading cannot  be  performed
732                    until  all  closing  ports are closed. Thus, as try_unload
733                    can,  in  almost  all  situations,   return   {ok,   pend‐
734                    ing_driver},  always  specify  at  least  {monitor,  pend‐
735                    ing_driver} in production code (see the monitor discussion
736                    earlier).
737
738                  {reload, ReloadOption}:
739                    This  option  is  used  to reload a driver from disk, most
740                    often in a code upgrade scenario. Having a  reload  option
741                    also  implies that parameter Path does not need to be con‐
742                    sistent with earlier loads of the driver.
743
744                    To reload a driver,  the  process  must  have  loaded  the
745                    driver  before,  that  is, there must be an active user of
746                    the driver in the process.
747
748                    The reload option can be either of the following:
749
750                    pending:
751                      With the atom pending, reloading is  requested  for  any
752                      driver  and  is effectuated when all ports opened to the
753                      driver are closed. The driver replacement in  this  case
754                      takes  place regardless if there are still pending users
755                      having the driver loaded.
756
757                      The option also triggers port-killing (if driver  option
758                      kill_ports  is  used)  although there are pending users,
759                      making it usable for forced driver replacement, but lay‐
760                      ing much responsibility on the driver users. The pending
761                      option is seldom used as one does not want  other  users
762                      to have loaded the driver when code change is underway.
763
764                    pending_driver:
765                      This option is more useful. Here, reloading is queued if
766                      the driver is not loaded by any  other  users,  but  the
767                      driver  has  opened  ports,  in  which  case  {ok, pend‐
768                      ing_driver} is returned  (a  monitor  option  is  recom‐
769                      mended).
770
771                    If  the  driver  is  unloaded (not present in the system),
772                    error  code  not_loaded  is  returned.  Option  reload  is
773                    intended  for  when the user has already loaded the driver
774                    in advance.
775
776              The function can  return  numerous  errors,  some  can  only  be
777              returned given a certain combination of options.
778
779              Some  errors  are  opaque and can only be interpreted by passing
780              them to function format_error/1, but  some  can  be  interpreted
781              directly:
782
783                {error,linked_in_driver}:
784                  The  driver  with the specified name is an Erlang statically
785                  linked-in driver, which cannot be manipulated with this API.
786
787                {error,inconsistent}:
788                  The driver is already loaded with other DriverOptionList  or
789                  a different literal Path argument.
790
791                  This  can  occur  even  if  a reload option is specified, if
792                  DriverOptionList differs from the current.
793
794                {error, permanent}:
795                  The driver has requested itself to be permanent,  making  it
796                  behave  like an Erlang linked-in driver and can no longer be
797                  manipulated with this API.
798
799                {error, pending_process}:
800                  The driver is loaded by other  users  when  option  {reload,
801                  pending_driver} was specified.
802
803                {error, pending_reload}:
804                  Driver  reload  is  already  requested  by another user when
805                  option {reload, ReloadOption} was specified.
806
807                {error, not_loaded_by_this_process}:
808                  Appears when option reload is specified. The driver Name  is
809                  present  in  the  system, but there is no user of it in this
810                  process.
811
812                {error, not_loaded}:
813                  Appears when option reload is specified. The driver Name  is
814                  not  in  the system. Only drivers loaded by this process can
815                  be reloaded.
816
817              All other error codes are to  be  translated  by  function  for‐
818              mat_error/1.  Notice  that  calls to format_error are to be per‐
819              formed from the same running  instance  of  the  Erlang  virtual
820              machine as the error is detected in, because of system-dependent
821              behavior concerning error values.
822
823              If the arguments or options are malformed, the function throws a
824              badarg exception.
825
826       try_unload(Name, OptionList) ->
827                     {ok, Status} |
828                     {ok, PendingStatus, Ref} |
829                     {error, ErrorAtom}
830
831              Types:
832
833                 Name = driver()
834                 OptionList = [Option]
835                 Option = {monitor, MonitorOption} | kill_ports
836                 MonitorOption = pending_driver | pending
837                 Status = unloaded | PendingStatus
838                 PendingStatus = pending_driver | pending_process
839                 Ref = reference()
840                 ErrorAtom =
841                     linked_in_driver |
842                     not_loaded |
843                     not_loaded_by_this_process |
844                     permanent
845
846              This is the low-level function to unload (or decrement reference
847              counts of) a driver. It can be used to force  port  killing,  in
848              much  the  same  way  as the driver option kill_ports implicitly
849              does. Also, it can trigger a monitor either because other  users
850              still  have  the  driver  loaded  or  because open ports use the
851              driver.
852
853              Unloading can be described as the process of telling the  emula‐
854              tor  that  this  particular  part of the code in this particular
855              process (that is, this user) no longer needs  the  driver.  That
856              can,  if  there  are  no  other  users, trigger unloading of the
857              driver, in which case the driver name disappears from the system
858              and  (if  possible) the memory occupied by the driver executable
859              code is reclaimed.
860
861              If the driver has option kill_ports set,  or  if  kill_ports  is
862              specified as an option to this function, all pending ports using
863              this driver are killed when unloading is done by the last  user.
864              If  no  port-killing  is  involved and there are open ports, the
865              unloading is delayed until no more open ports  use  the  driver.
866              If,  in  this  case,  another user (or even this user) loads the
867              driver again before the driver is unloaded, the unloading  never
868              takes place.
869
870              To  allow  the  user  to  request  unloading  to wait for actual
871              unloading, monitor triggers can be specified in  much  the  same
872              way  as  when loading. However, as users of this function seldom
873              are interested in more than decrementing the  reference  counts,
874              monitoring is seldom needed.
875
876          Note:
877              If  option  kill_ports  is used, monitor trigging is crucial, as
878              the ports are not guaranteed to be killed until  the  driver  is
879              unloaded.  Thus,  a  monitor  must be triggered for at least the
880              pending_driver case.
881
882
883              The possible monitor messages to expect are  the  same  as  when
884              using option unloaded to function monitor/2.
885
886              The function returns one of the following statuses upon success:
887
888                {ok, unloaded}:
889                  The driver was immediately unloaded, meaning that the driver
890                  name is now free to use by other drivers and, if the  under‐
891                  lying  OS  permits  it,  the  memory  occupied by the driver
892                  object code is now reclaimed.
893
894                  The driver can only be unloaded when there are no open ports
895                  using it and no more users require it to be loaded.
896
897                {ok, pending_driver}or {ok, pending_driver, reference()}:
898                  Indicates  that  this  call  removed  the last user from the
899                  driver, but there are still open ports using  it.  When  all
900                  ports  are  closed and no new users have arrived, the driver
901                  is reloaded and the name and memory reclaimed.
902
903                  This return value is valid even  if  option  kill_ports  was
904                  used,  as  killing ports can be a process that does not com‐
905                  plete immediately. However, the condition is  in  that  case
906                  transient.  Monitors  are  always  useful to detect when the
907                  driver is really unloaded.
908
909                {ok, pending_process}or {ok, pending_process, reference()}:
910                  The unload request is registered, but other users still hold
911                  the  driver.  Notice that the term pending_process can refer
912                  to the running process; there can be more than one  user  in
913                  the same process.
914
915                  This is a normal, healthy, return value if the call was just
916                  placed to inform the emulator that you have no  further  use
917                  of  the  driver.  It  is the most common return value in the
918                  most common scenario described in the introduction.
919
920              The function accepts the following parameters:
921
922                Name:
923                  Name is the name of the driver to be unloaded. The name  can
924                  be specified as an iolist() or as an atom().
925
926                OptionList:
927                  Argument  OptionList can be used to specify certain behavior
928                  regarding ports and triggering monitors under certain condi‐
929                  tions:
930
931                  kill_ports:
932                    Forces killing of all ports opened using this driver, with
933                    exit reason driver_unloaded, if you are the last  user  of
934                    the driver.
935
936                    If  other users have the driver loaded, this option has no
937                    effect.
938
939                    To get the consistent behavior of killing ports  when  the
940                    last user unloads, use driver option kill_ports when load‐
941                    ing the driver instead.
942
943                  {monitor, MonitorOption}:
944                    Creates a driver monitor if  the  condition  specified  in
945                    MonitorOption is true. The valid options are:
946
947                    pending_driver:
948                      Creates  a  driver  monitor if the return value is to be
949                      {ok, pending_driver}.
950
951                    pending:
952                      Creates a monitor if the  return  value  is  {ok,  pend‐
953                      ing_driver} or {ok, pending_process}.
954
955                    The  pending_driver  MonitorOption is by far the most use‐
956                    ful. It must be used to ensure that the driver  really  is
957                    unloaded  and  the ports closed whenever option kill_ports
958                    is used, or the driver can have been  loaded  with  driver
959                    option kill_ports.
960
961                    Using  the  monitor  triggers  in  the  call to try_unload
962                    ensures that the monitor is added before the unloading  is
963                    executed,  meaning  that  the  monitor  is always properly
964                    triggered, which is not the case if  monitor/2  is  called
965                    separately.
966
967              The function can return the following error conditions, all well
968              specified (no opaque values):
969
970                {error, linked_in_driver}:
971                  You were trying to unload  an  Erlang  statically  linked-in
972                  driver, which cannot be manipulated with this interface (and
973                  cannot be unloaded at all).
974
975                {error, not_loaded}:
976                  The driver Name is not present in the system.
977
978                {error, not_loaded_by_this_process}:
979                  The driver Name is present in the system, but  there  is  no
980                  user of it in this process.
981
982                  As  a  special  case, drivers can be unloaded from processes
983                  that have done no corresponding call to try_load/3  if,  and
984                  only  if, there are no users of the driver at all, which can
985                  occur if the process containing the last user dies.
986
987                {error, permanent}:
988                  The driver has made itself permanent, in which case  it  can
989                  no  longer  be  manipulated  by  this interface (much like a
990                  statically linked-in driver).
991
992              The function throws a badarg exception if the parameters are not
993              specified as described here.
994
995       unload(Name) -> ok | {error, ErrorDesc}
996
997              Types:
998
999                 Name = driver()
1000                 ErrorDesc = term()
1001
1002              Unloads,  or at least dereferences the driver named Name. If the
1003              caller is the last user of the driver, and no  more  open  ports
1004              use  the  driver, the driver gets unloaded. Otherwise, unloading
1005              is delayed until all ports are closed and no users remain.
1006
1007              If there are other users of the driver, the reference counts  of
1008              the  driver is merely decreased, so that the caller is no longer
1009              considered a user of the driver.  For  use  scenarios,  see  the
1010              description in the beginning of this module.
1011
1012              The  ErrorDesc  returned is an opaque value to be passed further
1013              on to function format_error/1. For more control over the  opera‐
1014              tion, use the try_unload/2 interface.
1015
1016              The function throws a badarg exception if the parameters are not
1017              specified as described here.
1018
1019       unload_driver(Name) -> ok | {error, ErrorDesc}
1020
1021              Types:
1022
1023                 Name = driver()
1024                 ErrorDesc = term()
1025
1026              Unloads, or at least dereferences the driver named Name. If  the
1027              caller  is the last user of the driver, all remaining open ports
1028              using the driver are killed with reason driver_unloaded and  the
1029              driver eventually gets unloaded.
1030
1031              If  there are other users of the driver, the reference counts of
1032              the driver is merely decreased, so that the caller is no  longer
1033              considered a user. For use scenarios, see the description in the
1034              beginning of this module.
1035
1036              The ErrorDesc returned is an opaque value to be  passed  further
1037              on  to function format_error/1. For more control over the opera‐
1038              tion, use the try_unload/2 interface.
1039
1040              The function throws a badarg exception if the parameters are not
1041              specified as described here.
1042

SEE ALSO

1044       erts:erl_driver(4), erts:driver_entry(4)
1045
1046
1047
1048Ericsson AB                     kernel 5.4.3.2                     erl_ddll(3)
Impressum