1erl_ddll(3) Erlang Module Definition erl_ddll(3)
2
6 erl_ddll - Dynamic driver loader and linker.
7
9 This module provides an interface for loading and unloading Erlang
10 linked-in drivers in runtime.
11 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 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 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 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 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 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 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 The following two pairs of functions support this scenario:
57 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 If a process having the driver loaded dies, it has the same
66 effect as if unloading is done.
67 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 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 The function names load_driver and unload_driver are kept for
81 backward compatibility.
82 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 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 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 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 To simplify driver replacement, avoid designing your system so that
108 more than one user has the driver loaded.
109 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 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 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 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 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
136 driver() = iolist() | atom()
137 path() = string() | atom()
139
141 demonitor(MonitorRef) -> ok
142 Types:
144 MonitorRef = reference()
146 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 The function throws a badarg exception if the parameter is not a
153 reference().
154 format_error(ErrorDesc) -> string()
156 Types:
158 ErrorDesc = term()
160 Takes an ErrorDesc returned by load, unload, or reload functions
162 and returns a string that describes the error or warning.
163 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 info() -> AllInfoList
173 Types:
175 AllInfoList = [DriverInfo]
177 DriverInfo = {DriverName, InfoList}
178 DriverName = string()
179 InfoList = [InfoItem]
180 InfoItem = {Tag :: atom(), Value :: term()}
181 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 info(Name) -> InfoList
187 Types:
189 Name = driver()
191 InfoList = [InfoItem, ...]
192 InfoItem = {Tag :: atom(), Value :: term()}
193 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 The following tags appears in the list:
200 * processes
202 * driver_options
204 * port_count
206 * linked_in_driver
208 * permanent
210 * awaiting_load
212 * awaiting_unload
214 For a detailed description of each value, see info/2.
216 The function throws a badarg exception if the driver is not
218 present in the system.
219 info(Name, Tag) -> Value
221 Types:
223 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 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 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 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 port_count:
250 Returns the number of ports (an integer() >= 0) using the
251 driver.
252 linked_in_driver:
254 Returns a boolean(), which is true if the driver is a stati‐
255 cally linked-in one, otherwise false.
256 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 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 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 If option linked_in_driver or permanent returns true, all other
275 options return linked_in_driver or permanent, respectively.
276 The function throws a badarg exception if the driver is not
278 present in the system or if the tag is not supported.
279 load(Path, Name) -> ok | {error, ErrorDesc}
281 Types:
283 Path = path()
285 Name = driver()
286 ErrorDesc = term()
287 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 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 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 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 It is not allowed to load multiple drivers with the same name
320 but with different Path parameters.
321 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 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 For more control over the error handling, use the try_load/3
335 interface instead.
336 The function throws a badarg exception if the parameters are not
338 specified as described here.
339 load_driver(Path, Name) -> ok | {error, ErrorDesc}
341 Types:
343 Path = path()
345 Name = driver()
346 ErrorDesc = term()
347 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 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 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 The function throws a badarg exception if the parameters are not
363 specified as described here.
364 loaded_drivers() -> {ok, Drivers}
366 Types:
368 Drivers = [Driver]
370 Driver = string()
371 Returns a list of all the available drivers, both (statically)
373 linked-in and dynamically loaded ones.
374 The driver names are returned as a list of strings rather than a
376 list of atoms for historical reasons.
377 For more information about drivers, see info.
379 monitor(Tag, Item) -> MonitorRef
381 Types:
383 Tag = driver
385 Item = {Name, When}
386 Name = driver()
387 When = loaded | unloaded | unloaded_only
388 MonitorRef = reference()
389 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 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 MonitorRef can also be used in subsequent calls to demonitor/1
401 to remove a monitor.
402 The function accepts the following parameters:
404 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 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 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 Setting a driver monitor for loading eventually leads to
428 one of the following messages being sent:
429 {'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 The user is expected to know if reloading is demanded
436 before creating a monitor for loading.
437 {'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 {'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 {'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 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 A driver monitor for unload eventually results in one of
467 the following messages being sent:
468 {'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 {'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 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 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 {'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 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 The function throws a badarg exception if the parameters are not
506 specified as described here.
507 reload(Path, Name) -> ok | {error, ErrorDesc}
509 Types:
511 Path = path()
513 Name = driver()
514 ErrorDesc = pending_process | OpaqueError
515 OpaqueError = term()
516 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 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 Note:
526 Avoid mixing multiple users with driver reload requests.
527 To avoid hanging on open ports, use function try_load/3 instead.
530 The Name and Path parameters have exactly the same meaning as
532 when calling the plain function load/2.
533 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 For more control over the error handling, use the try_load/3
540 interface instead.
541 The function throws a badarg exception if the parameters are not
543 specified as described here.
544 reload_driver(Path, Name) -> ok | {error, ErrorDesc}
546 Types:
548 Path = path()
550 Name = driver()
551 ErrorDesc = pending_process | OpaqueError
552 OpaqueError = term()
553 Works exactly as reload/2, but for drivers loaded with the
555 load_driver/2 interface.
556 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 For more details, see scenarios in this module description and
562 the function description for reload/2.
563 The function throws a badarg exception if the parameters are not
565 specified as described here.
566 try_load(Path, Name, OptionList) ->
568 {ok, Status} |
569 {ok, PendingStatus, Ref} |
570 {error, ErrorDesc}
571 Types:
573 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 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 {ok, loaded}:
605 The driver was loaded and is immediately usable.
606 {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 {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 {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 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 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 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 The function accepts the following parameters:
653 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 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 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 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 {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 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 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 {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 Only one MonitorOption can be specified. It is one of the
713 following:
714 * The atom pending, which means that a monitor is to be
716 created whenever a load operation is delayed,
717 * 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 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 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 {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 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 The reload option can be either of the following:
749 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 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 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 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 The function can return numerous errors, some can only be
777 returned given a certain combination of options.
778 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 {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 {error,inconsistent}:
788 The driver is already loaded with other DriverOptionList or
789 a different literal Path argument.
790 This can occur even if a reload option is specified, if
792 DriverOptionList differs from the current.
793 {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 {error, pending_process}:
800 The driver is loaded by other users when option {reload,
801 pending_driver} was specified.
802 {error, pending_reload}:
804 Driver reload is already requested by another user when
805 option {reload, ReloadOption} was specified.
806 {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 {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 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 If the arguments or options are malformed, the function throws a
824 badarg exception.
825 try_unload(Name, OptionList) ->
827 {ok, Status} |
828 {ok, PendingStatus, Ref} |
829 {error, ErrorAtom}
830 Types:
832 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 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 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 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 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 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 The possible monitor messages to expect are the same as when
884 using option unloaded to function monitor/2.
885 The function returns one of the following statuses upon success:
887 {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 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 {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 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 {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 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 The function accepts the following parameters:
921 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 OptionList:
927 Argument OptionList can be used to specify certain behavior
928 regarding ports and triggering monitors under certain condi‐
929 tions:
930 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 If other users have the driver loaded, this option has no
937 effect.
938 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 {monitor, MonitorOption}:
944 Creates a driver monitor if the condition specified in
945 MonitorOption is true. The valid options are:
946 pending_driver:
948 Creates a driver monitor if the return value is to be
949 {ok, pending_driver}.
950 pending:
952 Creates a monitor if the return value is {ok, pend‐
953 ing_driver} or {ok, pending_process}.
954 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 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 The function can return the following error conditions, all well
968 specified (no opaque values):
969 {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 {error, not_loaded}:
976 The driver Name is not present in the system.
977 {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 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 {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 The function throws a badarg exception if the parameters are not
993 specified as described here.
994 unload(Name) -> ok | {error, ErrorDesc}
996 Types:
998 Name = driver()
1000 ErrorDesc = term()
1001 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 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 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 The function throws a badarg exception if the parameters are not
1017 specified as described here.
1018 unload_driver(Name) -> ok | {error, ErrorDesc}
1020 Types:
1022 Name = driver()
1024 ErrorDesc = term()
1025 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 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 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 The function throws a badarg exception if the parameters are not
1041 specified as described here.
1042
1044 erts:erl_driver(4), erts:driver_entry(4)
1045Ericsson AB kernel 5.4.3.2 erl_ddll(3)