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 ob‐
19 ject 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 in‐
23 formation 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 interest in when the
62 unloading occurs. The driver is unloaded when no one needs it any
63 longer.
64 If a process having the driver loaded dies, it has the same ef‐
66 fect 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 un‐
77 load_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 de‐
105 mand 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 be‐
112 haviors 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 ap‐
169 peared 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 | driver_options | port_count |
227 linked_in_driver |
228 permanent | awaiting_load | awaiting_unload
229 Value = term()
230 Returns specific information about one aspect of a driver. Pa‐
232 rameter Tag specifies which aspect to get information about. The
233 return Value differs between different tags:
234 processes:
236 Returns all processes containing users of the specific driv‐
237 ers as a list of tuples {pid(),integer() >= 0}, where inte‐
238 ger() denotes the number of users in process pid().
239 driver_options:
241 Returns a list of the driver options provided when loading,
242 and any options set by the driver during initialization. The
243 only valid option is kill_ports.
244 port_count:
246 Returns the number of ports (an integer() >= 0) using the
247 driver.
248 linked_in_driver:
250 Returns a boolean(), which is true if the driver is a stati‐
251 cally linked-in one, otherwise false.
252 permanent:
254 Returns a boolean(), which is true if the driver has made
255 itself permanent (and is not a statically linked-in driver),
256 otherwise false.
257 awaiting_load:
259 Returns a list of all processes having monitors for loading
260 active. Each process is returned as {pid(),integer() >= 0},
261 where integer() is the number of monitors held by process
262 pid().
263 awaiting_unload:
265 Returns a list of all processes having monitors for unload‐
266 ing active. Each process is returned as {pid(),integer() >=
267 0}, where integer() is the number of monitors held by
268 process pid().
269 If option linked_in_driver or permanent returns true, all other
271 options return linked_in_driver or permanent, respectively.
272 The function throws a badarg exception if the driver is not
274 present in the system or if the tag is not supported.
275 load(Path, Name) -> ok | {error, ErrorDesc}
277 Types:
279 Path = path()
281 Name = driver()
282 ErrorDesc = term()
283 Loads and links the dynamic driver Name. Path is a file path to
285 the directory containing the driver. Name must be a shareable
286 object/dynamic library. Two drivers with different Path parame‐
287 ters cannot be loaded under the same name. Name is a string or
288 atom containing at least one character.
289 The Name specified is to correspond to the filename of the dy‐
291 namically loadable object file residing in the directory speci‐
292 fied as Path, but without the extension (that is, .so). The
293 driver name provided in the driver initialization routine must
294 correspond with the filename, in much the same way as Erlang
295 module names correspond to the names of the .beam files.
296 If the driver was previously unloaded, but is still present be‐
298 cause of open ports to it, a call to load/2 stops the unloading
299 and keeps the driver (as long as Path is the same), and ok is
300 returned. If you really want the object code to be reloaded, use
301 reload/2 or the low-level interface try_load/3 instead. See also
302 the description of different scenarios for loading/unloading in
303 the introduction.
304 If more than one process tries to load an already loaded driver
306 with the same Path, or if the same process tries to load it many
307 times, the function returns ok. The emulator keeps track of the
308 load/2 calls, so that a corresponding number of unload/2 calls
309 must be done from the same process before the driver gets un‐
310 loaded. It is therefore safe for an application to load a driver
311 that is shared between processes or applications when needed. It
312 can safely be unloaded without causing trouble for other parts
313 of the system.
314 It is not allowed to load multiple drivers with the same name
316 but with different Path parameters.
317 Note:
319 Path is interpreted literally, so that all loaders of the same
320 driver must specify the same literal Path string, although dif‐
321 ferent paths can point out the same directory in the file system
322 (because of use of relative paths and links).
323 On success, the function returns ok. On failure, the return
326 value is {error,ErrorDesc}, where ErrorDesc is an opaque term to
327 be translated into human readable form by function format_er‐
328 ror/1.
329 For more control over the error handling, use the try_load/3 in‐
331 terface instead.
332 The function throws a badarg exception if the parameters are not
334 specified as described here.
335 load_driver(Path, Name) -> ok | {error, ErrorDesc}
337 Types:
339 Path = path()
341 Name = driver()
342 ErrorDesc = term()
343 Works essentially as load/2, but loads the driver with other op‐
345 tions. All ports using the driver are killed with reason
346 driver_unloaded when the driver is to be unloaded.
347 The number of loads and unloads by different users influences
349 the loading and unloading of a driver file. The port killing
350 therefore only occurs when the last user unloads the driver, or
351 when the last process having loaded the driver exits.
352 This interface (or at least the name of the functions) is kept
354 for backward compatibility. Using try_load/3 with {driver_op‐
355 tions,[kill_ports]} in the option list gives the same effect re‐
356 garding the port killing.
357 The function throws a badarg exception if the parameters are not
359 specified as described here.
360 loaded_drivers() -> {ok, Drivers}
362 Types:
364 Drivers = [Driver]
366 Driver = string()
367 Returns a list of all the available drivers, both (statically)
369 linked-in and dynamically loaded ones.
370 The driver names are returned as a list of strings rather than a
372 list of atoms for historical reasons.
373 For more information about drivers, see info.
375 monitor(Tag, Item) -> MonitorRef
377 Types:
379 Tag = driver
381 Item = {Name, When}
382 Name = driver()
383 When = loaded | unloaded | unloaded_only
384 MonitorRef = reference()
385 Creates a driver monitor and works in many ways as erlang:moni‐
387 tor/2 in ERTS, does for processes. When a driver changes state,
388 the monitor results in a monitor message that is sent to the
389 calling process. MonitorRef returned by this function is in‐
390 cluded in the message sent.
391 As with process monitors, each driver monitor set only generates
393 one single message. The monitor is "destroyed" after the message
394 is sent, so it is then not needed to call demonitor/1.
395 MonitorRef can also be used in subsequent calls to demonitor/1
397 to remove a monitor.
398 The function accepts the following parameters:
400 Tag:
402 The monitor tag is always driver, as this function can only
403 be used to create driver monitors. In the future, driver
404 monitors will be integrated with process monitors, why this
405 parameter has to be specified for consistence.
406 Item:
408 Parameter Item specifies which driver to monitor (the driver
409 name) and which state change to monitor. The parameter is a
410 tuple of arity two whose first element is the driver name
411 and second element is one of the following:
412 loaded:
414 Notifies when the driver is reloaded (or loaded if loading
415 is underway). It only makes sense to monitor drivers that
416 are in the process of being loaded or reloaded. A future
417 driver name for loading cannot be monitored. That only re‐
418 sults in a DOWN message sent immediately. Monitoring for
419 loading is therefore most useful when triggered by func‐
420 tion try_load/3, where the monitor is created because the
421 driver is in such a pending state.
422 Setting a driver monitor for loading eventually leads to
424 one of the following messages being sent:
425 {'UP', reference(), driver, Name, loaded}:
427 This message is sent either immediately if the driver is
428 already loaded and no reloading is pending, or when
429 reloading is executed if reloading is pending.
430 The user is expected to know if reloading is demanded
432 before creating a monitor for loading.
433 {'UP', reference(), driver, Name, permanent}:
435 This message is sent if reloading was expected, but the
436 (old) driver made itself permanent before reloading. It
437 is also sent if the driver was permanent or statically
438 linked-in when trying to create the monitor.
439 {'DOWN', reference(), driver, Name, load_cancelled}:
441 This message arrives if reloading was underway, but the
442 requesting user cancelled it by dying or calling try_un‐
443 load/2 (or unload/1/unload_driver/1) again before it was
444 reloaded.
445 {'DOWN', reference(), driver, Name, {load_failure, Fail‐
447 ure}}:
448 This message arrives if reloading was underway but the
449 loading for some reason failed. The Failure term is one
450 of the errors that can be returned from try_load/3. The
451 error term can be passed to format_error/1 for transla‐
452 tion into human readable form. Notice that the transla‐
453 tion must be done in the same running Erlang virtual ma‐
454 chine as the error was detected in.
455 unloaded:
457 Monitors when a driver gets unloaded. If one monitors a
458 driver that is not present in the system, one immediately
459 gets notified that the driver got unloaded. There is no
460 guarantee that the driver was ever loaded.
461 A driver monitor for unload eventually results in one of
463 the following messages being sent:
464 {'DOWN', reference(), driver, Name, unloaded}:
466 The monitored driver instance is now unloaded. As the
467 unload can be a result of a reload/2 request, the driver
468 can once again have been loaded when this message ar‐
469 rives.
470 {'UP', reference(), driver, Name, unload_cancelled}:
472 This message is sent if unloading was expected, but
473 while the driver was waiting for all ports to get
474 closed, a new user of the driver appeared, and the un‐
475 loading was cancelled.
476 This message appears if {ok, pending_driver} was re‐
478 turned from try_unload/2 for the last user of the
479 driver, and then {ok, already_loaded} is returned from a
480 call to try_load/3.
481 If one really wants to monitor when the driver gets un‐
483 loaded, this message distorts the picture, because no
484 unloading was done. Option unloaded_only creates a moni‐
485 tor similar to an unloaded monitor, but never results in
486 this message.
487 {'UP', reference(), driver, Name, permanent}:
489 This message is sent if unloading was expected, but the
490 driver made itself permanent before unloading. It is
491 also sent if trying to monitor a permanent or statically
492 linked-in driver.
493 unloaded_only:
495 A monitor created as unloaded_only behaves exactly as one
496 created as unloaded except that the {'UP', reference(),
497 driver, Name, unload_cancelled} message is never sent, but
498 the monitor instead persists until the driver really gets
499 unloaded.
500 The function throws a badarg exception if the parameters are not
502 specified as described here.
503 reload(Path, Name) -> ok | {error, ErrorDesc}
505 Types:
507 Path = path()
509 Name = driver()
510 ErrorDesc = pending_process | OpaqueError
511 OpaqueError = term()
512 Reloads the driver named Name from a possibly different Path
514 than previously used. This function is used in the code change
515 scenario described in the introduction.
516 If there are other users of this driver, the function returns
518 {error, pending_process}, but if there are no other users, the
519 function call hangs until all open ports are closed.
520 Note:
522 Avoid mixing multiple users with driver reload requests.
523 To avoid hanging on open ports, use function try_load/3 instead.
526 The Name and Path parameters have exactly the same meaning as
528 when calling the plain function load/2.
529 On success, the function returns ok. On failure, the function
531 returns an opaque error, except the pending_process error de‐
532 scribed earlier. The opaque errors are to be translated into hu‐
533 man readable form by function format_error/1.
534 For more control over the error handling, use the try_load/3 in‐
536 terface instead.
537 The function throws a badarg exception if the parameters are not
539 specified as described here.
540 reload_driver(Path, Name) -> ok | {error, ErrorDesc}
542 Types:
544 Path = path()
546 Name = driver()
547 ErrorDesc = pending_process | OpaqueError
548 OpaqueError = term()
549 Works exactly as reload/2, but for drivers loaded with the
551 load_driver/2 interface.
552 As this interface implies that ports are killed when the last
554 user disappears, the function does not hang waiting for ports to
555 get closed.
556 For more details, see scenarios in this module description and
558 the function description for reload/2.
559 The function throws a badarg exception if the parameters are not
561 specified as described here.
562 try_load(Path, Name, OptionList) ->
564 {ok, Status} |
565 {ok, PendingStatus, Ref} |
566 {error, ErrorDesc}
567 Types:
569 Path = path()
571 Name = driver()
572 OptionList = [Option]
573 Option =
574 {driver_options, DriverOptionList} |
575 {monitor, MonitorOption} |
576 {reload, ReloadOption}
577 DriverOptionList = [DriverOption]
578 DriverOption = kill_ports
579 MonitorOption = ReloadOption = pending_driver | pending
580 Status = loaded | already_loaded | PendingStatus
581 PendingStatus = pending_driver | pending_process
582 Ref = reference()
583 ErrorDesc = ErrorAtom | OpaqueError
584 ErrorAtom =
585 linked_in_driver | inconsistent | permanent |
586 not_loaded_by_this_process | not_loaded | pending_reload
587 |
588 pending_process
589 OpaqueError = term()
590 Provides more control than the load/2/reload/2 and
592 load_driver/2/reload_driver/2 interfaces. It never waits for
593 completion of other operations related to the driver, but imme‐
594 diately returns the status of the driver as one of the follow‐
595 ing:
596 {ok, loaded}:
598 The driver was loaded and is immediately usable.
599 {ok, already_loaded}:
601 The driver was already loaded by another process or is in
602 use by a living port, or both. The load by you is registered
603 and a corresponding try_unload is expected sometime in the
604 future.
605 {ok, pending_driver}or {ok, pending_driver, reference()}:
607 The load request is registered, but the loading is delayed
608 because an earlier instance of the driver is still waiting
609 to get unloaded (open ports use it). Still, unload is ex‐
610 pected when you are done with the driver. This return value
611 mostly occurs when options {reload,pending_driver} or
612 {reload,pending} are used, but can occur when another user
613 is unloading a driver in parallel and driver option
614 kill_ports is set. In other words, this return value always
615 needs to be handled.
616 {ok, pending_process}or {ok, pending_process, reference()}:
618 The load request is registered, but the loading is delayed
619 because an earlier instance of the driver is still waiting
620 to get unloaded by another user (not only by a port, in
621 which case {ok,pending_driver} would have been returned).
622 Still, unload is expected when you are done with the driver.
623 This return value only occurs when option {reload,pending}
624 is used.
625 When the function returns {ok, pending_driver} or {ok, pend‐
627 ing_process}, one can get information about when the driver is
628 actually loaded by using option {monitor, MonitorOption}.
629 When monitoring is requested, and a corresponding {ok, pend‐
631 ing_driver} or {ok, pending_process} would be returned, the
632 function instead returns a tuple {ok, PendingStatus, refer‐
633 ence()} and the process then gets a monitor message later, when
634 the driver gets loaded. The monitor message to expect is de‐
635 scribed in the function description of monitor/2.
636 Note:
638 In case of loading, monitoring can not only get triggered by us‐
639 ing option {reload, ReloadOption}, but also in special cases
640 where the load error is transient. Thus, {monitor, pend‐
641 ing_driver} is to be used under basically all real world circum‐
642 stances.
643 The function accepts the following parameters:
646 Path:
648 The file system path to the directory where the driver ob‐
649 ject file is located. The filename of the object file (minus
650 extension) must correspond to the driver name (used in pa‐
651 rameter Name) and the driver must identify itself with the
652 same name. Path can be provided as an iolist(), meaning it
653 can be a list of other iolist()s, characters (8-bit inte‐
654 gers), or binaries, all to be flattened into a sequence of
655 characters.
656 The (possibly flattened) Path parameter must be consistent
658 throughout the system. A driver is to, by all users, be
659 loaded using the same literal Path. The exception is when
660 reloading is requested, in which case Path can be specified
661 differently. Notice that all users trying to load the driver
662 later need to use the new Path if Path is changed using a
663 reload option. This is yet another reason to have only one
664 loader of a driver one wants to upgrade in a running system.
665 Name:
667 This parameter is the name of the driver to be used in sub‐
668 sequent calls to function erlang:open_port in ERTS. The name
669 can be specified as an iolist() or an atom(). The name spec‐
670 ified when loading is used to find the object file (with the
671 help of Path and the system-implied extension suffix, that
672 is, .so). The name by which the driver identifies itself
673 must also be consistent with this Name parameter, much as
674 the module name of a Beam file much corresponds to its file‐
675 name.
676 OptionList:
678 Some options can be specified to control the loading opera‐
679 tion. The options are specified as a list of two-tuples. The
680 tuples have the following values and meanings:
681 {driver_options, DriverOptionList}:
683 This is to provide options that changes its general behav‐
684 ior and "sticks" to the driver throughout its lifespan.
685 The driver options for a specified driver name need always
687 to be consistent, even when the driver is reloaded, mean‐
688 ing that they are as much a part of the driver as the
689 name.
690 The only allowed driver option is kill_ports, which means
692 that all ports opened to the driver are killed with exit
693 reason driver_unloaded when no process any longer has the
694 driver loaded. This situation arises either when the last
695 user calls try_unload/2, or when the last process having
696 loaded the driver exits.
697 {monitor, MonitorOption}:
699 A MonitorOption tells try_load/3 to trigger a driver moni‐
700 tor under certain conditions. When the monitor is trig‐
701 gered, the function returns a three-tuple {ok, PendingSta‐
702 tus, reference()}, where reference() is the monitor refer‐
703 ence for the driver monitor.
704 Only one MonitorOption can be specified. It is one of the
706 following:
707 * The atom pending, which means that a monitor is to be
709 created whenever a load operation is delayed,
710 * The atom pending_driver, in which a monitor is created
712 whenever the operation is delayed because of open ports
713 to an otherwise unused driver.
714 Option pending_driver is of little use, but is present for
716 completeness, as it is well defined which reload options
717 that can give rise to which delays. However, it can be a
718 good idea to use the same MonitorOption as the ReloadOp‐
719 tion, if present.
720 If reloading is not requested, it can still be useful to
722 specify option monitor, as forced unloads (driver option
723 kill_ports or option kill_ports to try_unload/2) trigger a
724 transient state where driver loading cannot be performed
725 until all closing ports are closed. Thus, as try_unload
726 can, in almost all situations, return {ok, pend‐
727 ing_driver}, always specify at least {monitor, pend‐
728 ing_driver} in production code (see the monitor discussion
729 earlier).
730 {reload, ReloadOption}:
732 This option is used to reload a driver from disk, most of‐
733 ten in a code upgrade scenario. Having a reload option
734 also implies that parameter Path does not need to be con‐
735 sistent with earlier loads of the driver.
736 To reload a driver, the process must have loaded the
738 driver before, that is, there must be an active user of
739 the driver in the process.
740 The reload option can be either of the following:
742 pending:
744 With the atom pending, reloading is requested for any
745 driver and is effectuated when all ports opened to the
746 driver are closed. The driver replacement in this case
747 takes place regardless if there are still pending users
748 having the driver loaded.
749 The option also triggers port-killing (if driver option
751 kill_ports is used) although there are pending users,
752 making it usable for forced driver replacement, but lay‐
753 ing much responsibility on the driver users. The pending
754 option is seldom used as one does not want other users
755 to have loaded the driver when code change is underway.
756 pending_driver:
758 This option is more useful. Here, reloading is queued if
759 the driver is not loaded by any other users, but the
760 driver has opened ports, in which case {ok, pend‐
761 ing_driver} is returned (a monitor option is recom‐
762 mended).
763 If the driver is unloaded (not present in the system), er‐
765 ror code not_loaded is returned. Option reload is intended
766 for when the user has already loaded the driver in ad‐
767 vance.
768 The function can return numerous errors, some can only be re‐
770 turned given a certain combination of options.
771 Some errors are opaque and can only be interpreted by passing
773 them to function format_error/1, but some can be interpreted di‐
774 rectly:
775 {error,linked_in_driver}:
777 The driver with the specified name is an Erlang statically
778 linked-in driver, which cannot be manipulated with this API.
779 {error,inconsistent}:
781 The driver is already loaded with other DriverOptionList or
782 a different literal Path argument.
783 This can occur even if a reload option is specified, if
785 DriverOptionList differs from the current.
786 {error, permanent}:
788 The driver has requested itself to be permanent, making it
789 behave like an Erlang linked-in driver and can no longer be
790 manipulated with this API.
791 {error, pending_process}:
793 The driver is loaded by other users when option {reload,
794 pending_driver} was specified.
795 {error, pending_reload}:
797 Driver reload is already requested by another user when op‐
798 tion {reload, ReloadOption} was specified.
799 {error, not_loaded_by_this_process}:
801 Appears when option reload is specified. The driver Name is
802 present in the system, but there is no user of it in this
803 process.
804 {error, not_loaded}:
806 Appears when option reload is specified. The driver Name is
807 not in the system. Only drivers loaded by this process can
808 be reloaded.
809 All other error codes are to be translated by function for‐
811 mat_error/1. Notice that calls to format_error are to be per‐
812 formed from the same running instance of the Erlang virtual ma‐
813 chine as the error is detected in, because of system-dependent
814 behavior concerning error values.
815 If the arguments or options are malformed, the function throws a
817 badarg exception.
818 try_unload(Name, OptionList) ->
820 {ok, Status} |
821 {ok, PendingStatus, Ref} |
822 {error, ErrorAtom}
823 Types:
825 Name = driver()
827 OptionList = [Option]
828 Option = {monitor, MonitorOption} | kill_ports
829 MonitorOption = pending_driver | pending
830 Status = unloaded | PendingStatus
831 PendingStatus = pending_driver | pending_process
832 Ref = reference()
833 ErrorAtom =
834 linked_in_driver | not_loaded |
835 not_loaded_by_this_process |
836 permanent
837 This is the low-level function to unload (or decrement reference
839 counts of) a driver. It can be used to force port killing, in
840 much the same way as the driver option kill_ports implicitly
841 does. Also, it can trigger a monitor either because other users
842 still have the driver loaded or because open ports use the
843 driver.
844 Unloading can be described as the process of telling the emula‐
846 tor that this particular part of the code in this particular
847 process (that is, this user) no longer needs the driver. That
848 can, if there are no other users, trigger unloading of the
849 driver, in which case the driver name disappears from the system
850 and (if possible) the memory occupied by the driver executable
851 code is reclaimed.
852 If the driver has option kill_ports set, or if kill_ports is
854 specified as an option to this function, all pending ports using
855 this driver are killed when unloading is done by the last user.
856 If no port-killing is involved and there are open ports, the un‐
857 loading is delayed until no more open ports use the driver. If,
858 in this case, another user (or even this user) loads the driver
859 again before the driver is unloaded, the unloading never takes
860 place.
861 To allow the user to request unloading to wait for actual un‐
863 loading, monitor triggers can be specified in much the same way
864 as when loading. However, as users of this function seldom are
865 interested in more than decrementing the reference counts, moni‐
866 toring is seldom needed.
867 Note:
869 If option kill_ports is used, monitor trigging is crucial, as
870 the ports are not guaranteed to be killed until the driver is
871 unloaded. Thus, a monitor must be triggered for at least the
872 pending_driver case.
873 The possible monitor messages to expect are the same as when us‐
876 ing option unloaded to function monitor/2.
877 The function returns one of the following statuses upon success:
879 {ok, unloaded}:
881 The driver was immediately unloaded, meaning that the driver
882 name is now free to use by other drivers and, if the under‐
883 lying OS permits it, the memory occupied by the driver ob‐
884 ject code is now reclaimed.
885 The driver can only be unloaded when there are no open ports
887 using it and no more users require it to be loaded.
888 {ok, pending_driver}or {ok, pending_driver, reference()}:
890 Indicates that this call removed the last user from the
891 driver, but there are still open ports using it. When all
892 ports are closed and no new users have arrived, the driver
893 is reloaded and the name and memory reclaimed.
894 This return value is valid even if option kill_ports was
896 used, as killing ports can be a process that does not com‐
897 plete immediately. However, the condition is in that case
898 transient. Monitors are always useful to detect when the
899 driver is really unloaded.
900 {ok, pending_process}or {ok, pending_process, reference()}:
902 The unload request is registered, but other users still hold
903 the driver. Notice that the term pending_process can refer
904 to the running process; there can be more than one user in
905 the same process.
906 This is a normal, healthy, return value if the call was just
908 placed to inform the emulator that you have no further use
909 of the driver. It is the most common return value in the
910 most common scenario described in the introduction.
911 The function accepts the following parameters:
913 Name:
915 Name is the name of the driver to be unloaded. The name can
916 be specified as an iolist() or as an atom().
917 OptionList:
919 Argument OptionList can be used to specify certain behavior
920 regarding ports and triggering monitors under certain condi‐
921 tions:
922 kill_ports:
924 Forces killing of all ports opened using this driver, with
925 exit reason driver_unloaded, if you are the last user of
926 the driver.
927 If other users have the driver loaded, this option has no
929 effect.
930 To get the consistent behavior of killing ports when the
932 last user unloads, use driver option kill_ports when load‐
933 ing the driver instead.
934 {monitor, MonitorOption}:
936 Creates a driver monitor if the condition specified in
937 MonitorOption is true. The valid options are:
938 pending_driver:
940 Creates a driver monitor if the return value is to be
941 {ok, pending_driver}.
942 pending:
944 Creates a monitor if the return value is {ok, pend‐
945 ing_driver} or {ok, pending_process}.
946 The pending_driver MonitorOption is by far the most use‐
948 ful. It must be used to ensure that the driver really is
949 unloaded and the ports closed whenever option kill_ports
950 is used, or the driver can have been loaded with driver
951 option kill_ports.
952 Using the monitor triggers in the call to try_unload en‐
954 sures that the monitor is added before the unloading is
955 executed, meaning that the monitor is always properly
956 triggered, which is not the case if monitor/2 is called
957 separately.
958 The function can return the following error conditions, all well
960 specified (no opaque values):
961 {error, linked_in_driver}:
963 You were trying to unload an Erlang statically linked-in
964 driver, which cannot be manipulated with this interface (and
965 cannot be unloaded at all).
966 {error, not_loaded}:
968 The driver Name is not present in the system.
969 {error, not_loaded_by_this_process}:
971 The driver Name is present in the system, but there is no
972 user of it in this process.
973 As a special case, drivers can be unloaded from processes
975 that have done no corresponding call to try_load/3 if, and
976 only if, there are no users of the driver at all, which can
977 occur if the process containing the last user dies.
978 {error, permanent}:
980 The driver has made itself permanent, in which case it can
981 no longer be manipulated by this interface (much like a
982 statically linked-in driver).
983 The function throws a badarg exception if the parameters are not
985 specified as described here.
986 unload(Name) -> ok | {error, ErrorDesc}
988 Types:
990 Name = driver()
992 ErrorDesc = term()
993 Unloads, or at least dereferences the driver named Name. If the
995 caller is the last user of the driver, and no more open ports
996 use the driver, the driver gets unloaded. Otherwise, unloading
997 is delayed until all ports are closed and no users remain.
998 If there are other users of the driver, the reference counts of
1000 the driver is merely decreased, so that the caller is no longer
1001 considered a user of the driver. For use scenarios, see the de‐
1002 scription in the beginning of this module.
1003 The ErrorDesc returned is an opaque value to be passed further
1005 on to function format_error/1. For more control over the opera‐
1006 tion, use the try_unload/2 interface.
1007 The function throws a badarg exception if the parameters are not
1009 specified as described here.
1010 unload_driver(Name) -> ok | {error, ErrorDesc}
1012 Types:
1014 Name = driver()
1016 ErrorDesc = term()
1017 Unloads, or at least dereferences the driver named Name. If the
1019 caller is the last user of the driver, all remaining open ports
1020 using the driver are killed with reason driver_unloaded and the
1021 driver eventually gets unloaded.
1022 If there are other users of the driver, the reference counts of
1024 the driver is merely decreased, so that the caller is no longer
1025 considered a user. For use scenarios, see the description in the
1026 beginning of this module.
1027 The ErrorDesc returned is an opaque value to be passed further
1029 on to function format_error/1. For more control over the opera‐
1030 tion, use the try_unload/2 interface.
1031 The function throws a badarg exception if the parameters are not
1033 specified as described here.
1034
1036 erts:erl_driver(4), erts:driver_entry(4)
1037Ericsson AB kernel 9.1 erl_ddll(3)