2.2 - Initialising the profiler

Once the Oso Memory Profiler SDK is compiled into your application, the only thing left to do is actually initialise it.

Technically speaking, the profiler responds to memory allocation requests from the host application, and partially initialises itself. You still have to implement a single function (OsoMP_InitialiseCallback) that is called by the profiler as part of the initialisation procedure.

It is the responsibility of your implementation of this function to complete the initialisation process by calling OsoMP_Initialise. The parameters you pass to this function determine whether your profile data will be stored on the local file system (or on a mapped network share), or whether it will be sent via TCP directly to the Oso Memory Profiler. Or both.

It should be noted that this function will most probably be called as soon as the runtime libraries begin initialising themselves, so as a rule you cannot rely on global variables to be initialised before your callback function is called. You should also not try to allocate memory using standard language memory allocation functions. (I.e., the functions that you are profiling.) It should be safe to call OS-level functions to allocate memory if necessary.

Local Profiling

An extremely simple example implementation of your callback function to initialise for local profiling is as follows:

A more complex example might add a random value to the filename so that multiple profiles can be stored alongside each other without having to move them away before each run.

Remote Profiling

An alternative example callback function to initialise for remote profiling is as follows:

Obviously this example will merely connect to the Oso Memory Profiler running on the same machine as the application being profiled. It should also be noted that the port number can be changed within the preferences of the Oso Memory Profiler, and that listening for incoming connections must also be enabled in the preferences.

The astute reader will notice that it is possible to pass both a filename and network connection settings to OsoMP_Initialise. Doing so will enable both local and remote profiling in a single session.

Additional Setup

Once OsoMP_Initialise returns, your implementation of this function should register any other settings required for your profiling session. These can include none, some, or all of the following:

• Defining the session name through a call to OsoMP_SessionName.
• Setting the name of the main thread with OsoMP_ThreadName.
• Defining new attribute types through calls to OsoMP_NewAttributeType.
• Registering new block types with OsoMP_NewBlockType.
• Adding new warning and error conditions through calls to OsoMP_NewWarningCondition and OsoMP_NewErrorCondition respectively.

It is recommended that any of the above are performed in the order listed above.

Terminating Profiling

Once the profiler is initialised and running correctly, the only thing left to do is shut your application down correctly so that no profile data is lost due to not being flushed correctly. This is managed through calling OsoMP_Closedown before your application exits. For more information, please refer to the documentation for OsoMP_Closedown.