com.facebook.soloader

Class SoLoader

java.lang.Object

com.facebook.soloader.SoLoader

@ThreadSafe
public class SoLoader
extends java.lang.Object

Native code loader.

To load a native library, call the static method loadLibrary(java.lang.String) from the static initializer of the Java class declaring the native methods. The argument should be the library's short name.

Note: SoLoader is enabled in the source code by default but disabled for the OSS package via meta-data config. The application could define com.facebook.soloader.enabled metadata entry to override the default behavior.

For example, if the native code is in libmy_jni_methods.so:

 class MyClass {
   static {
     SoLoader.loadLibrary("my_jni_methods");
   }
 }
 

Before any library can be loaded SoLoader needs to be initialized. The application using SoLoader should do that by calling SoLoader.init early on app initialization path. The call must happen before any class using SoLoader in its static initializer is loaded.

An example of the meta data entry to enable SoLoader:

     <application ...>
       <meta-data
           tools:replace="android:value"
           android:name="com.facebook.soloader.enabled"
           android:value="true" />
     </application>
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	SoLoader.WrongAbiError

Field Summary

Fields

Modifier and Type	Field and Description
static int	SOLOADER_ALLOW_ASYNC_INIT Allow deferring some initialization work to asynchronous background threads.
static int	SOLOADER_DISABLE_BACKUP_SOSOURCE In some contexts, using a backup so source in case of so corruption is not feasible e.g.
static int	SOLOADER_DISABLE_FS_SYNC_JOB Experiment ONLY: disable the fsync job in soSource
static int	SOLOADER_DONT_TREAT_AS_SYSTEMAPP Deprecated.
static int	SOLOADER_ENABLE_DIRECT_SOSOURCE Deprecated.
static int	SOLOADER_ENABLE_EXOPACKAGE Enable the exopackage SoSource.
static int	SOLOADER_ENABLE_SYSTEMLOAD_WRAPPER_SOSOURCE Experiment ONLY: use the SystemLoadWrapperSoSource to instead of the directApk/Application soSource.
static int	SOLOADER_EXPLICITLY_ENABLE_BACKUP_SOSOURCE For compatibility, we need explicitly enable the backup soSource.
static int	SOLOADER_LOOK_IN_ZIP
static int	SOLOADER_SKIP_MERGED_JNI_ONLOAD Skip calling JNI_OnLoad if the library is merged.
static java.lang.String	TAG
static java.lang.String	VERSION

Constructor Summary

Constructors

Constructor and Description
SoLoader()

Method Summary

Modifier and Type	Method and Description
static boolean	areSoSourcesAbisSupported() This function ensure that every SoSources Abi is supported for at least one abi in SysUtil.getSupportedAbis
static SoSource[]	cloneSoSources()
static void	deinitForTest() Make shared-library loading delegate to the system.
static java.lang.String[]	getLibraryDependencies(java.lang.String libName) Gets the dependencies of a library.
static java.lang.String	getLibraryPath(java.lang.String libName) Gets the full path of a library.
static int	getLoadedLibrariesCount() Returns count of already loaded so libraries
static java.io.File	getSoFile(java.lang.String shortName) Returns the so file for the specified library.
static int	getSoSourcesVersion()
static void	init(android.content.Context context, boolean nativeExopackage) Backward compatibility.
static void	init(android.content.Context context, int flags)
static void	init(android.content.Context context, int flags, SoFileLoader soFileLoader) Initializes native code loading for this app; this class's other static facilities cannot be used until this init(android.content.Context, int) is called.
static boolean	isInitialized()
static boolean	loadLibrary(java.lang.String shortName)
static boolean	loadLibrary(java.lang.String shortName, int loadFlags) Load a shared library, initializing any JNI binding it contains.
static java.lang.String	makeLdLibraryPath() Retrieve an LD_LIBRARY_PATH value suitable for using the native linker to resolve our shared libraries.
static void	prependSoSource(SoSource extraSoSource) Add a new source of native libraries.
static void	setInTestMode() Turn shared-library loading into a no-op.
static void	setSystemLoadLibraryWrapper(SystemLoadLibraryWrapper wrapper) Provide a wrapper object for calling System.loadLibrary(java.lang.String).
static java.io.File	unpackLibraryAndDependencies(java.lang.String shortName) Unpack library and its dependencies, returning the location of the unpacked library file.
static boolean	useDepsFile(android.content.Context context, boolean async, boolean extractToDisk) Enables the use of a deps file to fetch the native library dependencies to avoid reading them from the ELF files.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

TAG

public static final java.lang.String TAG

See Also:

Constant Field Values

VERSION

public static java.lang.String VERSION

SOLOADER_ENABLE_EXOPACKAGE

public static final int SOLOADER_ENABLE_EXOPACKAGE

Enable the exopackage SoSource.

See Also:

Constant Field Values

SOLOADER_ALLOW_ASYNC_INIT

public static final int SOLOADER_ALLOW_ASYNC_INIT

Allow deferring some initialization work to asynchronous background threads. Shared libraries are nevertheless ready to load as soon as init returns.

See Also:

Constant Field Values

SOLOADER_LOOK_IN_ZIP

public static final int SOLOADER_LOOK_IN_ZIP

See Also:

Constant Field Values

SOLOADER_DISABLE_BACKUP_SOSOURCE

public static final int SOLOADER_DISABLE_BACKUP_SOSOURCE

In some contexts, using a backup so source in case of so corruption is not feasible e.g. lack of write permissions to the library path.

See Also:

Constant Field Values

SOLOADER_SKIP_MERGED_JNI_ONLOAD

public static final int SOLOADER_SKIP_MERGED_JNI_ONLOAD

Skip calling JNI_OnLoad if the library is merged. This is necessary for libraries that don't define JNI_OnLoad and are only loaded for their side effects (like static constructors registering callbacks). DO NOT use this to allow implicit JNI registration (by naming your methods Java_com_facebook_whatever) because that is buggy on Android.

See Also:

Constant Field Values

SOLOADER_DONT_TREAT_AS_SYSTEMAPP

@Deprecated
public static final int SOLOADER_DONT_TREAT_AS_SYSTEMAPP

Deprecated.

Deprecated, NO EFFECT

See Also:

Constant Field Values

SOLOADER_ENABLE_DIRECT_SOSOURCE

@Deprecated
public static final int SOLOADER_ENABLE_DIRECT_SOSOURCE

Deprecated.

In API level 23 and above, it’s possible to open a .so file directly from your APK. Enabling this flag will explicitly add the direct SoSource in soSource list.

See Also:

Constant Field Values

SOLOADER_EXPLICITLY_ENABLE_BACKUP_SOSOURCE

public static final int SOLOADER_EXPLICITLY_ENABLE_BACKUP_SOSOURCE

For compatibility, we need explicitly enable the backup soSource. This flag conflicts with SOLOADER_DISABLE_BACKUP_SOSOURCE, you should only set one of them or none.

See Also:

Constant Field Values

SOLOADER_DISABLE_FS_SYNC_JOB

public static final int SOLOADER_DISABLE_FS_SYNC_JOB

Experiment ONLY: disable the fsync job in soSource

See Also:

Constant Field Values

SOLOADER_ENABLE_SYSTEMLOAD_WRAPPER_SOSOURCE

public static final int SOLOADER_ENABLE_SYSTEMLOAD_WRAPPER_SOSOURCE

Experiment ONLY: use the SystemLoadWrapperSoSource to instead of the directApk/Application soSource. This could work on the apps w/o superpack or any other so file compression.

See Also:

Constant Field Values

Constructor Detail

SoLoader

public SoLoader()

Method Detail

init

public static void init(android.content.Context context,
                        int flags)
                 throws java.io.IOException

Throws:

java.io.IOException

init

public static void init(android.content.Context context,
                        int flags,
                        @Nullable
                        SoFileLoader soFileLoader)
                 throws java.io.IOException

Initializes native code loading for this app; this class's other static facilities cannot be used until this init(android.content.Context, int) is called. This method is idempotent: calls after the first are ignored.

Parameters:

context - application context

flags - Zero or more of the SOLOADER_* flags

soFileLoader - the custom SoFileLoader, you can implement your own loader

Throws:

java.io.IOException - IOException

init

public static void init(android.content.Context context,
                        boolean nativeExopackage)

Backward compatibility.

Parameters:

context - application context

nativeExopackage - pass SOLOADER_ENABLE_EXOPACKAGE as flags if true

See Also:

What is exopackage?

setInTestMode

public static void setInTestMode()

Turn shared-library loading into a no-op. Useful in special circumstances.

deinitForTest

public static void deinitForTest()

Make shared-library loading delegate to the system. Useful for tests.

setSystemLoadLibraryWrapper

public static void setSystemLoadLibraryWrapper(SystemLoadLibraryWrapper wrapper)

Provide a wrapper object for calling System.loadLibrary(java.lang.String). This is useful for controlling which ClassLoader libraries are loaded into.

Parameters:

wrapper - the wrapper you wanna set

getLibraryPath

@Nullable
public static java.lang.String getLibraryPath(java.lang.String libName)
                                                 throws java.io.IOException

Gets the full path of a library.

Parameters:

libName - the library file name, including the prefix and extension.

Returns:

the full path of the library, or null if it is not found in none of the SoSources.

Throws:

java.io.IOException - if there is an error calculating the canonical path of libName

cloneSoSources

public static SoSource[] cloneSoSources()

getLibraryDependencies

@Nullable
public static java.lang.String[] getLibraryDependencies(java.lang.String libName)
                                                           throws java.io.IOException

Gets the dependencies of a library.

Parameters:

libName - the library file name, including the prefix and extension.

Returns:

An array naming the dependencies of the library, or null if it is not found in any SoSources

Throws:

java.io.IOException - if there is an error reading libName

getSoFile

@Nullable
public static java.io.File getSoFile(java.lang.String shortName)

Returns the so file for the specified library. Returns null if the library does not exist or if it's not backed by a file.

Parameters:

shortName - Name of library to find, without "lib" prefix or ".so" suffix

Returns:

the File object of the so file

loadLibrary

public static boolean loadLibrary(java.lang.String shortName)

loadLibrary

public static boolean loadLibrary(java.lang.String shortName,
                                  int loadFlags)
                           throws java.lang.UnsatisfiedLinkError

Load a shared library, initializing any JNI binding it contains.

Parameters:

shortName - Name of library to find, without "lib" prefix or ".so" suffix

loadFlags - Control flags for the loading behavior. See available flags under SoSource (LOAD_FLAG_XXX).

Returns:

Whether the library was loaded as a result of this call (true), or was already loaded through a previous call to SoLoader (false).

Throws:

java.lang.UnsatisfiedLinkError

unpackLibraryAndDependencies

public static java.io.File unpackLibraryAndDependencies(java.lang.String shortName)
                                                 throws java.lang.UnsatisfiedLinkError

Unpack library and its dependencies, returning the location of the unpacked library file. All non-system dependencies of the given library will either be on LD_LIBRARY_PATH or will be in the same directory as the returned File.

Parameters:

shortName - Name of library to find, without "lib" prefix or ".so" suffix

Returns:

Unpacked DSO location

Throws:

java.lang.UnsatisfiedLinkError

isInitialized

public static boolean isInitialized()

getSoSourcesVersion

public static int getSoSourcesVersion()

prependSoSource

public static void prependSoSource(SoSource extraSoSource)
                            throws java.io.IOException

Add a new source of native libraries. SoLoader consults the new source before any currently-installed source.

Parameters:

extraSoSource - The SoSource to install

Throws:

java.io.IOException - IOException

makeLdLibraryPath

public static java.lang.String makeLdLibraryPath()

Retrieve an LD_LIBRARY_PATH value suitable for using the native linker to resolve our shared libraries.

Returns:

the LD_LIBRARY_PATH in string

areSoSourcesAbisSupported

public static boolean areSoSourcesAbisSupported()

This function ensure that every SoSources Abi is supported for at least one abi in SysUtil.getSupportedAbis

Returns:

true if all SoSources have their Abis supported

useDepsFile

public static boolean useDepsFile(android.content.Context context,
                                  boolean async,
                                  boolean extractToDisk)

Enables the use of a deps file to fetch the native library dependencies to avoid reading them from the ELF files. The file is expected to be in the APK in assets/native_deps.txt. Returns true on success, false on failure. On failure, dependencies will be read from ELF files instead of the deps file.

Parameters:

context - - Application context, used to find native deps file in APK

async - - If true, initialization will occur in a background thread and we library loading will wait for initialization to complete.

extractToDisk - - If true, the native deps file will be extract from the APK and written to disk. This can be useful when the file is compressed in the APK, since we can prevent decompressing the file every time.

Returns:

True if initialization succeeded, false otherwise. Always returns true if async is true.

getLoadedLibrariesCount

public static int getLoadedLibrariesCount()

Returns count of already loaded so libraries

Returns:

number of loaded libraries