PlatformLibrary protocols

Instances of PlatformLibrary are used to look up function or data addresses in operating system shared libraries. PlatformLibrary is used implicitly by instances of PlatformFunction.

Each instance has a logical name and a physical name. The logical name is the name used to refer to the library in Smalltalk (for example, the library name used in a PlatformFunction). The physical name (which can be the same as the logical name) is the name that is passed to the operating system. The PlatformLibrary class keeps a list of all instances that it creates. This way, multiple instances with the same logical name are never created.

Creating PlatformLibrary instances

Instances of PlatformLibrary can be created either declaratively or programmatically.

To create a PlatformLibrary instance declaratively, add a line to the [PlatformLibrary Name Mapping] stanza in the .INI file using the logical name as the keyword and the physical name as the value. Please refer to the PlatformLibrary name mapping stanza page in the Smalltalk User’s Guide for examples of using this approach. This approach is particularly effective for a PlatformLibrarary whose physical name changes based on the operating system platform that the program is executing on because a different .INI file can be supplied for each platform.

To create a PlatformLibrary instance programmatically, code an invocation of the mapLogicalName:toPhysicalName: method in a location where it will be run each time the image is started (the startUp class method on Application is a good place for this).

Here are 2 examples of creating PlatformLibrary instances programmatically. The second example illustrates a situation more easily handled through declarative creation of a PlatformLibrary instance.

A simple creation invocation from CgImageSupport:

PlatformLibrary mapLogicalName: 'CgImageSupport’ toPhysicalName: ‘escgi40’.

A more complex invocation from SciSslOpenSSLInterface:

(System osType = 'WIN32_NT')

ifTrue: [

PlatformLibrary mapLogicalName: 'CRYPTO_LIB' toPhysicalName: 'libeay32.dll'.

PlatformLibrary mapLogicalName: 'SSL_LIB' toPhysicalName: 'ssleay32.dll'.

PlatformLibrary mapLogicalName: 'THREAD_LIB' toPhysicalName: 'vasslthreads.dll']

ifFalse: [

PlatformLibrary mapLogicalName: 'CRYPTO_LIB' toPhysicalName: 'libcrypto.so'.

PlatformLibrary mapLogicalName: 'SSL_LIB' toPhysicalName: 'libssl.so'.

PlatformLibrary mapLogicalName: 'THREAD_LIB' toPhysicalName: 'vasslthreads.so'].

The invocation of the mapLogicalName:toPhysicalName: method is often encapsulated (by convention) in a method named bindSharedLibrary.

Closing PlatformLibrary instances

When an application owning a PlatformLibrary instance (by nature of having created it) is unloaded from the image, the PlatformLibrary instance should be closed. This is usually done in the removing method by invoking closeLogicalName: (declarative creation) or removeMappingForLogicalName: (programmatic creation). The invocation of the closeLogicalName: or removeMappingForLogicalName: methods is often encapsulated (by convention) in a method named unbindSharedLibrary.

Class methods: mapping logical names to physical names

mapLogicalName:toPhysicalName:

Sets the mapping for the platform library's logical name to the specified physical name. If a PlatformLibrary with the specified logical name exists, closes it and sets its physical name as indicated. If a new instance of PlatformLibrary with the logical name is created at some later time, its physical name is set as indicated. The logical name and the physical name must be a String. The physical name must be either a String or nil. If the physical name is nil, all functions in the library are looked up in the user primitive table instead of an operating system shared library.

closeLogicalName:

If a PlatformLibrary instance with the logical name exists, closes it, but does not remove the logical to physical name mapping information. The logical name must be a String.

removeMappingForLogicalName:

Removes the mapping for the logical name, if any. If a PlatformLibrary instance with the logical name exists, closes it, and sets its physical name to the logical name. If a new instance of PlatformLibrary with the logical name is created at some later time, its physical name is set to the logical name. The logical name must be a String.

Class methods: instance creation

logicalName:

If a PlatformLibrary with the logical name already exists, answers it. Otherwise, answers a new instance whose logical name is as indicated and whose physical name is set according to the mappings. The logical name must be a String.

Class methods: miscellaneous

removeUnreferencedLibraries

Closes all instances of PlatformLibrary. Discards any instances that are not referenced from at least one PlatformFunction. This method does not remove any mappings.

Instance methods: accessing

logicalName

Answers the logical name of the receiver (a String).

physicalName

Answers the physical name of the receiver (a String or nil).

Instance methods: library operations

getAddress:

Answers the address (a positive Integer) of the library object in the receiver. The library object must be a String or an Integer. If the library object cannot be found, a walkback occurs.

close

Closes the receiver. All PlatformFunctions that reside in the receiver are unbound.