blob: 1a17c38d15f1cb93848e4c159b8907864994dc45 [file] [log] [blame]
// Copyright 2016 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Module Overview: Memory Reporting API.
//
// Provides an interface for memory reporting.
#ifndef STARBOARD_MEMORY_REPORTER_H_
#define STARBOARD_MEMORY_REPORTER_H_
#include "starboard/configuration.h"
#include "starboard/export.h"
#include "starboard/types.h"
#ifdef __cplusplus
extern "C" {
#endif
///////////////////////////////////////////////////////////////////////////////
// These are callbacks used by SbMemoryReporter to report memory
// allocation and deallocation.
///////////////////////////////////////////////////////////////////////////////
// A function to report a memory allocation from SbMemoryAllocate(). Note that
// operator new calls SbMemoryAllocate which will delegate to this callback.
typedef void (*SbMemoryReporterOnAlloc)(void* context, const void* memory,
size_t size);
// A function to report a memory deallocation from SbMemoryDeallcoate(). Note
// that operator delete calls SbMemoryDeallocate which will delegate to this
// callback.
typedef void (*SbMemoryReporterOnDealloc)(void* context, const void* memory);
// A function to report a memory mapping from SbMemoryMap().
typedef void (*SbMemoryReporterOnMapMemory)(void* context, const void* memory,
size_t size);
// A function to report a memory unmapping from SbMemoryUnmap().
typedef void (*SbMemoryReporterOnUnMapMemory)(void* context,
const void* memory,
size_t size);
// SbMemoryReporter allows memory reporting via user-supplied functions.
// The void* context is passed to every call back.
// It's strongly recommended that C-Style struct initialization is used
// so that the arguments can be typed check by the compiler.
// For example,
// SbMemoryReporter mem_reporter = { MallocCallback, .... context };
struct SbMemoryReporter {
// Callback to report allocations.
SbMemoryReporterOnAlloc on_alloc_cb;
// Callback to report deallocations.
SbMemoryReporterOnDealloc on_dealloc_cb;
// Callback to report memory map.
SbMemoryReporterOnMapMemory on_mapmem_cb;
// Callback to report memory unmap.
SbMemoryReporterOnUnMapMemory on_unmapmem_cb;
// Optional, is passed to callbacks as first argument.
void* context;
};
// Sets the MemoryReporter. Any previous memory reporter is unset. No lifetime
// management is done internally on input pointer.
//
// Returns true if the memory reporter was set with no errors. If an error
// was reported then check the log for why it failed.
//
// Note that other than a thread-barrier-write of the input pointer, there is
// no thread safety guarantees with this function due to performance
// considerations. It's recommended that this be called once during the
// lifetime of the program, or not at all. Do not delete the supplied pointer,
// ever.
// Example (Good):
// SbMemoryReporter* mem_reporter = new ...;
// SbMemorySetReporter(&mem_reporter);
// ...
// SbMemorySetReporter(NULL); // allow value to leak.
// Example (Bad):
// SbMemoryReporter* mem_reporter = new ...;
// SbMemorySetReporter(&mem_reporter);
// ...
// SbMemorySetReporter(NULL);
// delete mem_reporter; // May crash.
SB_EXPORT bool SbMemorySetReporter(struct SbMemoryReporter* tracker);
#ifdef __cplusplus
} // extern "C"
#endif
#endif // STARBOARD_MEMORY_REPORTER_H_