DXR is a code search and navigation tool aimed at making sense of large projects. It supports full-text and regex searches as well as structural queries.

Mercurial (5b81998bb7ab)

VCS Links

Line Code
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302
/* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

/*
**  stoptions.h
**
**  Abstract the spacetrace options into a reusable format, such that
**      many different pieces of the code can utilize the common list.
*/

/*
**  There are three types of options.
**  The destinction is quite important.
**
**  CMD options are accessible from only the comamnd line.
**      Such options should be considered global/static for the entire
**          run of the application.
**      Once set, no one can change these options during the run.
**
**  WEB options are accessible from the web server options page.
**      Such options can and will be changed on a per user basis during
**          the run of the application.
**      You should NEVER make an option a WEB only option, as this will
**          break batch mode processing, and will likely not correctly
**          define the options structure itself.
**      These options will control the data caching used in the application
**          to match a client to a cache of data.
**
**  ALL options are both CMD and WEB options, with the properties of WEB
**      options (the user will change these on a per client basis).
**      Most likely this is the type of option you will desire to create.
*/

/*
**  All types of options have some combination of the following elements:
**
**  option_name             The name of the option.
**  option_genre            Area the option effects; STOptionGenre.
**  default_value           The default value for the option.
**  array_size              Used to size a string array.
**  multiplier              Some numbers prefer conversion.
**  option_help             Help text to explain the option.
**
**  NOTE! that the multiplier should be applied to the default value if you
**      are going to assign the default_value into anything.
**
**  Be very aware that adding things to a particular genre, or adding a genre,
**      may completely screw up the caching algorithms of SpaceTrace.
**  See contextLookup() or ask someone that knows if you are in doubt.
**
**  The actual definition of the WEB and CMD macros however is left to the
**      end user.
**  We cover those that you do not define herein.
*/
#if !defined(ST_CMD_OPTION_BOOL)
#define ST_CMD_OPTION_BOOL(option_name, option_genre, option_help)
#endif
#if !defined(ST_WEB_OPTION_BOOL)
#define ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
#endif
#if !defined(ST_CMD_OPTION_STRING)
#define ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help)
#endif
#if !defined(ST_WEB_OPTION_STRING)
#define ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
#endif
#if !defined(ST_CMD_OPTION_STRING_ARRAY)
#define ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
#endif
#if !defined(ST_WEB_OPTION_STRING_ARRAY)
#define ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
#endif
#if !defined(ST_CMD_OPTION_STRING_PTR_ARRAY)
#define ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
#endif
#if !defined(ST_WEB_OPTION_STRING_PTR_ARRAY)
#define ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
#endif
#if !defined(ST_CMD_OPTION_UINT32)
#define ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
#endif
#if !defined(ST_WEB_OPTION_UINT32)
#define ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
#endif
#if !defined(ST_CMD_OPTION_UINT64)
#define ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
#endif
#if !defined(ST_WEB_OPTION_UINT64)
#define ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
#endif

/*
**  ALL macros expand to both CMD and WEB macros.
**  This basically means such options are accessible from both the command
**      line and from the web options.
*/
#define ST_ALL_OPTION_BOOL(option_name, option_genre, option_help) \
    ST_CMD_OPTION_BOOL(option_name, option_genre, option_help) \
    ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
#define ST_ALL_OPTION_STRING(option_name, option_genre, default_value, option_help) \
    ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help) \
    ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
#define ST_ALL_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
    ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
    ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
#define ST_ALL_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
    ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
    ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
#define ST_ALL_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
    ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
    ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
#define ST_ALL_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
    ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
    ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)



/****************************************************************************
**  BEGIN, THE OPTIONS
**
**  Order is somewhat relevant in that it will control 3 different things:
**      1)  The order the members will be in the options structure.
**      2)  The order the options are presented on the command line.
**      3)  The order the options are presented on the web options page.
*/

ST_ALL_OPTION_STRING(CategoryName,
                     CategoryGenre,
                     ST_ROOT_CATEGORY_NAME,
                     "Specify a category for reports to focus upon.\n"
                     "See http://lxr.mozilla.org/mozilla/source/tools/trace-malloc/rules.txt\n")

ST_ALL_OPTION_UINT32(OrderBy,
                     DataSortGenre,
                     ST_SIZE, /* for dp :-D */
                     1,
                     "Determine the sort order.\n"
                     "0 by weight (size * lifespan).\n"
                     "1 by size.\n"
                     "2 by lifespan.\n"
                     "3 by allocation count.\n"
                     "4 by performance cost.\n")

ST_ALL_OPTION_STRING_ARRAY(RestrictText,
                           DataSetGenre,
                           ST_SUBSTRING_MATCH_MAX,
                           "Exclude allocations which do not have this text in their backtrace.\n"
                           "Multiple restrictions are treated as a logical AND operation.\n")

ST_ALL_OPTION_UINT32(SizeMin,
                     DataSetGenre,
                     0,
                     1,
                     "Exclude allocations that are below this byte size.\n")

ST_ALL_OPTION_UINT32(SizeMax,
                     DataSetGenre,
                     0xFFFFFFFF,
                     1,
                     "Exclude allocations that are above this byte size.\n")

ST_ALL_OPTION_UINT32(LifetimeMin,
                     DataSetGenre,
                     ST_DEFAULT_LIFETIME_MIN,
                     ST_TIMEVAL_RESOLUTION,
                     "Allocations must live this number of seconds or be ignored.\n")

ST_ALL_OPTION_UINT32(LifetimeMax,
                     DataSetGenre,
                     ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
                     ST_TIMEVAL_RESOLUTION,
                     "Allocations living longer than this number of seconds will be ignored.\n")

ST_ALL_OPTION_UINT32(TimevalMin,
                     DataSetGenre,
                     0,
                     ST_TIMEVAL_RESOLUTION,
                     "Allocations existing solely before this second will be ignored.\n"
                     "Live allocations at this second and after can be considered.\n")

ST_ALL_OPTION_UINT32(TimevalMax,
                     DataSetGenre,
                     ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
                     ST_TIMEVAL_RESOLUTION,
                     "Allocations existing solely after this second will be ignored.\n"
                     "Live allocations at this second and before can be considered.\n")

ST_ALL_OPTION_UINT32(AllocationTimevalMin,
                     DataSetGenre,
                     0,
                     ST_TIMEVAL_RESOLUTION,
                     "Live and dead allocations created before this second will be ignored.\n")

ST_ALL_OPTION_UINT32(AllocationTimevalMax,
                     DataSetGenre,
                     ST_TIMEVAL_MAX / ST_TIMEVAL_RESOLUTION,
                     ST_TIMEVAL_RESOLUTION,
                     "Live and dead allocations created after this second will be ignored.\n")

ST_ALL_OPTION_UINT32(AlignBy,
                     DataSizeGenre,
                     ST_DEFAULT_ALIGNMENT_SIZE,
                     1,
                     "All allocation sizes are made to be a multiple of this number.\n"
                     "Closer to actual heap conditions; set to 1 for true sizes.\n")

ST_ALL_OPTION_UINT32(Overhead,
                     DataSizeGenre,
                     ST_DEFAULT_OVERHEAD_SIZE,
                     1,
                     "After alignment, all allocations are made to increase by this number.\n"
                     "Closer to actual heap conditions; set to 0 for true sizes.\n")

ST_ALL_OPTION_UINT32(ListItemMax,
                     UIGenre,
                     500,
                     1,
                     "Specifies the maximum number of list items to present in each list.\n")

ST_ALL_OPTION_UINT64(WeightMin,
                     DataSetGenre,
                     LL_INIT(0, 0),
                     LL_INIT(0, 1),
                     "Exclude allocations that are below this weight (lifespan * size).\n")

ST_ALL_OPTION_UINT64(WeightMax,
                     DataSetGenre,
                     LL_INIT(0xFFFFFFFF, 0xFFFFFFFF),
                     LL_INIT(0, 1),
                     "Exclude allocations that are above this weight (lifespan * size).\n")

ST_CMD_OPTION_STRING(FileName,
                     DataSetGenre,
                     "-",
                     "Specifies trace-malloc input file.\n"
                     "\"-\" indicates stdin will be used as input.\n")

ST_CMD_OPTION_STRING(CategoryFile,
                     CategoryGenre,
                     "rules.txt",
                     "Specifies the category rules file.\n"
                     "This file contains rules about how to categorize allocations.\n")

                     
ST_CMD_OPTION_UINT32(HttpdPort,
                     ServerGenre,
                     1969,
                     1,
                     "Specifies the default port the web server will listen on.\n")

ST_CMD_OPTION_STRING(OutputDir,
                     BatchModeGenre,
                     ".",
                     "Specifies a directory to output batch mode requests.\n"
                     "The directory must exist and must not use a trailing slash.\n")

ST_CMD_OPTION_STRING_PTR_ARRAY(BatchRequest,
                               BatchModeGenre,
                               "This implicitly turns on batch mode.\n"
                               "Save each requested file into the output dir, then exit.\n")

ST_CMD_OPTION_UINT32(Contexts,
                     ServerGenre,
                     1,
                     1,
                     "How many configurations to cache at the cost of a lot of memory.\n"
                     "Dedicated servers can cache more client configurations for performance.\n")

ST_CMD_OPTION_BOOL(Help,
                   UIGenre,
                   "Show command line help.\n"
                   "See http://www.mozilla.org/projects/footprint/spaceTrace.html\n")

/*
**  END, THE OPTIONS
****************************************************************************/

/*
**  Everything is undefined after the header is included.
**  This sets it up for multiple inclusion if so desired.
*/
#undef ST_ALL_OPTION_BOOL
#undef ST_CMD_OPTION_BOOL
#undef ST_WEB_OPTION_BOOL
#undef ST_ALL_OPTION_STRING
#undef ST_CMD_OPTION_STRING
#undef ST_WEB_OPTION_STRING
#undef ST_ALL_OPTION_STRING_ARRAY
#undef ST_CMD_OPTION_STRING_ARRAY
#undef ST_WEB_OPTION_STRING_ARRAY
#undef ST_ALL_OPTION_STRING_PTR_ARRAY
#undef ST_CMD_OPTION_STRING_PTR_ARRAY
#undef ST_WEB_OPTION_STRING_PTR_ARRAY
#undef ST_ALL_OPTION_UINT32
#undef ST_CMD_OPTION_UINT32
#undef ST_WEB_OPTION_UINT32
#undef ST_ALL_OPTION_UINT64
#undef ST_CMD_OPTION_UINT64
#undef ST_WEB_OPTION_UINT64