js/public/AllocationLogging.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*-
   2  * vim: set ts=8 sts=2 et sw=2 tw=80:
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 /*
   8  * Embedder-supplied tracking of the allocation and deallocation of various
   9  * non-garbage-collected objects in SpiderMonkey.
  10  *
  11  * This functionality is intended to track allocation of non-user-visible
  12  * structures, for debugging the C++ of an embedding.  It is not intended to
  13  * give the end user visibility into allocations in JS.  Instead see
  14  * AllocationRecording.h for such functionality.
  15  */
  16
  17 #ifndef js_AllocationLogging_h
  18 #define js_AllocationLogging_h
  19
  20 #include <stdint.h>  // uint32_t
  21
  22 #include "jstypes.h"  // JS_PUBLIC_API
  23
  24 namespace JS {
  25
  26 using LogCtorDtor = void (*)(void*, const char*, uint32_t);
  27
  28 /**
  29  * Set global functions used to monitor classes to highlight leaks.
  30  *
  31  * For each C++ class that uses these mechanisms, the allocation of an instance
  32  * will log the constructor call, and its subsequent deallocation will log the
  33  * destructor call.  If only the former occurs, the instance/allocation is
  34  * leaked.  With carefully-written logging functions, this can be used to debug
  35  * the origin of the leaks.
  36  */
  37 extern JS_PUBLIC_API void SetLogCtorDtorFunctions(LogCtorDtor ctor,
  38                                                   LogCtorDtor dtor);
  39
  40 /**
  41  * Log the allocation of |self|, having a type uniquely identified by the string
  42  * |type|, with allocation size |sz|.
  43  *
  44  * You generally should use |JS_COUNT_CTOR| and |JS_COUNT_DTOR| instead of
  45  * using this function directly.
  46  */
  47 extern JS_PUBLIC_API void LogCtor(void* self, const char* type, uint32_t sz);
  48
  49 /**
  50  * Log the deallocation of |self|, having a type uniquely identified by the
  51  * string |type|, with allocation size |sz|.
  52  *
  53  * You generally should use |JS_COUNT_CTOR| and |JS_COUNT_DTOR| instead of
  54  * using this function directly.
  55  */
  56 extern JS_PUBLIC_API void LogDtor(void* self, const char* type, uint32_t sz);
  57
  58 /**
  59  * Within each non-delegating constructor of a |Class|, use
  60  * |JS_COUNT_CTOR(Class);| to log the allocation of |this|.  (If you do this in
  61  * delegating constructors, you might count a single allocation multiple times.)
  62  */
  63 #define JS_COUNT_CTOR(Class) \
  64   (::JS::LogCtor(static_cast<void*>(this), #Class, sizeof(Class)))
  65
  66 /**
  67  * Within the destructor of a |Class|, use |JS_COUNT_DTOR(Class);| to log the
  68  * deallocation of |this|.
  69  */
  70 #define JS_COUNT_DTOR(Class) \
  71   (::JS::LogDtor(static_cast<void*>(this), #Class, sizeof(Class)))
  72
  73 }  // namespace JS
  74
  75 #endif  // js_AllocationLogging_h