Superluminal

https://superluminal.eu/docs/
Admin
Superluminal is a high-performance CPU profiling tool designed for C++, Rust, and .NET applications...
Tokens:23,627
Snippets:166
Trust Score:8.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Load PerformanceAPI DLL and use API functions in C

Source: https://superluminal.eu/docs/documentation.html

This example shows how to manually load PerformanceAPI.dll using LoadLibraryW and GetProcAddress, then call PerformanceAPI_GetAPI to obtain the API function table. It includes a main function that loads the API from the default installation path and adds an instrumentation event. Note that a helper function PerformanceAPI_LoadFrom is provided in PerformanceAPI_loader.h that does this work automatically.

```C
// Note: this is just an example; a full working implementation is provided in PerformanceAPI_loader.h
int PerformanceAPI_Load(const wchar_t* inPathToDLL, PerformanceAPI_Functions* outFunctions)
{
    HMODULE module = LoadLibraryW(inPathToDLL);
    if (module == NULL)
        return 0;

    PerformanceAPI_GetAPI_Func getAPI = (PerformanceAPI_GetAPI_Func)((void*)GetProcAddress(module, "PerformanceAPI_GetAPI"));
    if (getAPI == NULL)
    {
        FreeLibrary(module);
        return 0;
    }

    if (getAPI(PERFORMANCEAPI_VERSION, outFunctions) == 0)
    {
        FreeLibrary(module);
        return 0;
    }

    return 1;
}

int main(int _argc, char** _argv)
{
    PerformanceAPI_Functions performanceAPI;

    // Load the API from the default installation path
    if (!PerformanceAPI_Load(L"C:\\Program Files\\Superluminal\\Performance\\API\\dll\\x64\\PerformanceAPI.dll", &functions))
        return -1;

    // Add an instrumentation event
    {
      performanceAPI.BeginEvent("Example Instrumentation", NULL, PERFORMANCEAPI_DEFAULT_COLOR);    
      // ... some long running code here ...    
      performanceAPI.EndEvent();
    }

    return 0;
}
```

--------------------------------

### Instrumenting Fiber Execution

Source: https://superluminal.eu/docs/documentation.html

Example showing how to register a fiber, wrap fiber switches with Begin/End calls, and unregister the fiber when finished.

```cpp
void fiberFunc()
{
	uint64_t currentFiber = (uint64_t)GetCurrentFiber();
	
	// When the fiber starts running, register it
	PerformanceAPI_RegisterFiber(currentFiber);

	// ...do Fiber work here...

	// Wrap the call to SwitchToFiber in Begin/End calls
	PerformanceAPI_BeginFiberSwitch(currentFiber, (uint64_t)someOtherFiber); 
	SwitchToFiber(someOtherFiber);
	PerformanceAPI_EndFiberSwitch(currentFiber);

	// ...do more Fiber work here...

	// When fiber stops running, unregister it
	PerformanceAPI_UnregisterFiber(currentFiber);
}
```

--------------------------------

### Instrumenting Functions and Scopes

Source: https://superluminal.eu/docs/documentation.html

A functional example demonstrating the use of instrumentation macros for functions, nested scopes with contextual data, and color-coded scopes.

```cpp
#include "PerformanceAPI/PerformanceAPI.h"
#include <thread>
#include <chrono>

void MacroInstrumentedFunction()
{
    PERFORMANCEAPI_INSTRUMENT_FUNCTION();
    std::this_thread::sleep_for(std::chrono::milliseconds(16));

    {
        PERFORMANCEAPI_INSTRUMENT_DATA("Nested scope with contextual data", "");
        std::this_thread::sleep_for(std::chrono::milliseconds(16));
    }

    {
        PERFORMANCEAPI_INSTRUMENT_COLOR("Nested scope with color", PERFORMANCEAPI_MAKE_COLOR(255, 0, 0));
        std::this_thread::sleep_for(std::chrono::milliseconds(16));
    }
}
```

--------------------------------

### PerformanceAPI_RegisterFiber

Source: https://superluminal.eu/docs/documentation.html

Registers a fiber with the profiling system. Must be called when a fiber starts running.

```APIDOC
## PerformanceAPI_RegisterFiber

### Description
Registers a fiber with the instrumentation system. This must be called when a fiber starts running.

### Method
RegisterFiber

### Endpoint
PerformanceAPI_RegisterFiber

### Parameters
- **fiberId** (uint64_t) - Required - The unique identifier of the fiber.

### Request Example
```
void fiberFunc()
{
    uint64_t currentFiber = (uint64_t)GetCurrentFiber();
    PerformanceAPI_RegisterFiber(currentFiber);
}
```

### Response
No response value is returned.
```

--------------------------------

### PerformanceAPI_BeginEvent

Source: https://superluminal.eu/docs/documentation.html

Signals the start of an instrumentation event. Must be matched with PerformanceAPI_EndEvent within the same function.

```APIDOC
## PerformanceAPI_BeginEvent

### Description
Signals the start of an instrumentation event. The event ID must be a static string. Optional data can be supplied.

### Method
BeginEvent

### Endpoint
PerformanceAPI_BeginEvent

### Parameters
- **id** (const char*) - Required - A static string representing the event ID.
- **data** (const char*) - Optional - A string with per-instance data.

### Response
No return value.

### Note
Calls to BeginEvent and corresponding EndEvent must be within the same function.
```

--------------------------------

### Copied timing information format from Source & Disassembly view

Source: https://superluminal.eu/docs/documentation.html

Example of the verbose timing information copied to the clipboard when using CTRL+SHIFT+C or the context menu. Shows per-line percentages and durations in microseconds.

```plaintext
342 |                        | 	int sum = 0;
343 | 12.66693%  (1ms 133µs) | 	for (int i = 0; i != 1000000; ++i)
344 | 14.77809%  (1ms 322µs) | 		sum += i;
345 |                        | 
346 |                        | 	if (inLevel == 0)
347 | 43.66842%  (3ms 907µs) | 		Function0();
348 |                        | }
```

--------------------------------

### C++ example program using Performance API for fiber support

Source: https://superluminal.eu/docs/documentation.html

This C++ program uses Superluminal's Performance API to set the current thread name and instrument two passes with BeginEvent/EndEvent macros. When profiled with Superluminal, it produces a profile with the events as shown.

```cpp
int main(int _argc, char** _argv)
{
  PerformanceAPI_SetCurrentThreadName("Main");

  {
      PerformanceAPI_BeginEvent("Pass 1", nullptr, PERFORMANCEAPI_DEFAULT_COLOR);
      for (int i = 0; i < 5; ++i)
      {
          MacroInstrumentedFunction();
      }
      PerformanceAPI_EndEvent();
  }

  {
      PerformanceAPI_BeginEvent("Pass 2", nullptr, PERFORMANCEAPI_DEFAULT_COLOR);
      for (int i = 0; i < 5; ++i)
      {
          MacroInstrumentedFunction();
      }
      PerformanceAPI_EndEvent();
  }

  return 0;
}
```

--------------------------------

### Recursive function example (C++ call graph folding illustration)

Source: https://superluminal.eu/docs/documentation.html

Illustrates indirect recursion for the explained folding feature. `MyRecursiveFunction` calls `Function0` or `Function1` depending on `inLevel`, and those functions call back into the recursion. Use to understand how folding merges exclusive time and child calls in Superluminal's Call Graph and Source view.

```cpp
void Function0()
{
	MyRecursiveFunction(1);
}

void Function1()
{
	MyRecursiveFunction(2);
}

void MyRecursiveFunction(int inLevel)
{
	// Some expensive operation
	switch (inLevel)
	{
	case 0:
		Function0();
		break;

	case 1:
		Function1();
		break;
	}
}
```

--------------------------------

### PerformanceAPI_BeginFiberSwitch

Source: https://superluminal.eu/docs/documentation.html

Marks the beginning of a fiber switch. Must be paired with PerformanceAPI_EndFiberSwitch.

```APIDOC
## PerformanceAPI_BeginFiberSwitch

### Description
Signals that a fiber switch is about to occur. The call must be paired with PerformanceAPI_EndFiberSwitch.

### Method
BeginFiberSwitch

### Endpoint
PerformanceAPI_BeginFiberSwitch

### Parameters
- **currentFiber** (uint64_t) - Required - The identifier of the currently running fiber.
- **otherFiber** (uint64_t) - Required - The identifier of the fiber to switch to.

### Example
```javascript
PerformanceAPI_BeginFiberSwitch(currentFiber, (uint64_t)someOtherFiber); 
SwitchToFiber(someOtherFiber);
PerformanceAPI_EndFiberSwitch(currentFiber);
```

### Response
No return value.
```
Tokens:
Raw