10.3Class DynLib

Creates a reference to a dynamic library.

Class DynLib( path )

path	The path from which to load the library (local system).
Raise	DynLibError on load failed.

This class allows to load functions from dynamic link library or shared objects.

On error, a more specific error description is returned in the extra parameter of the raised DynLibError instance.

Methods
get	Gets a dynamic symbol in this library.
query	Gets a dynamic symbol in this library.
unload	Unloads a dynamic library from memory.

Methods

get

Gets a dynamic symbol in this library.

DynLib.get( decl, [deletor] )

decl	The C header declaration.
deletor	C Header declaration of a function ivoked at collection of generated items.
Return	On success an instance of DynFunction class.
Raise	DynLibError if this instance is not valid (i.e. if used after an unload). DynLibError if the function named in decl parameter cannot be resolved in the library. ParseError in case of invalid declaration used as decl parameter.

On success, the returned DynFunction instance has all the needed informations to perform calls directed to the foreign library.

As the call method of DynFunction is performing the actual call, if the other informations are not needed, it is possible to get a callable symbol by accessing directly the call property:

      allocate = mylib.get( "struct THING* allocate()" )
      use = mylib.get( "void use( struct THING* data )" )
      dispose = mylib.get( "void dispose( struct THING* data )" )

      // create an item
      item = allocate()

      // use it
      use( item )

      // and free it
      dispose( item )

Note: The allocate, use and dispose items in this examples are DynFunction instances; they can be directly called as they offer a call() override.

In cases like the one in this example, it is possible to associate an automatic deletor function directly in the first call:

      allocate = mylib.get( "struct THING* allocate()", "void dispose( struct THING* data )" )
      use = mylib.get( "void use( struct THING* data )" )

      // create an item
      item = allocate()

      // use it
      use( item )

      // ...

Doing so, the items returned via a function returning opaque data (struct pointers) are automatically deleted when the garbage collector is called.

See the main page of this document for more details on safety.

query

Gets a dynamic symbol in this library.

DynLib.query( decl, [deletor] )

decl	The C header declaration.
deletor	C Header declaration of a function ivoked at collection of generated items.
Return	On success an instance of DynFunction class; nil if the symbol can't be found.
Raise	DynLibError if this instance is not valid (i.e. if used after an unload). ParseError in case of invalid declaration used as decl parameter.

This function is equivalent to DynLib.get, except for the fact that it returns nil instead of raising an error if the given function is not found. Some program logic may prefer a raise when the desired function is not there (as it is supposed to be there), other may prefer just to peek at the library for optional content.

unload

Unloads a dynamic library from memory.

DynLib.unload()

Raise

DynLibError on failure.

Using any of the functions loaded from this library after this call may cause immediate crash of the host application.