1 /* -*- Mode: C; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 4 -*-
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/. */
10 ** Abstract the spacetrace options into a reusable format, such that
11 ** many different pieces of the code can utilize the common list.
15 ** There are three types of options.
16 ** The destinction is quite important.
18 ** CMD options are accessible from only the comamnd line.
19 ** Such options should be considered global/static for the entire
20 ** run of the application.
21 ** Once set, no one can change these options during the run.
23 ** WEB options are accessible from the web server options page.
24 ** Such options can and will be changed on a per user basis during
25 ** the run of the application.
26 ** You should NEVER make an option a WEB only option, as this will
27 ** break batch mode processing, and will likely not correctly
28 ** define the options structure itself.
29 ** These options will control the data caching used in the application
30 ** to match a client to a cache of data.
32 ** ALL options are both CMD and WEB options, with the properties of WEB
33 ** options (the user will change these on a per client basis).
34 ** Most likely this is the type of option you will desire to create.
38 ** All types of options have some combination of the following elements:
40 ** option_name The name of the option.
41 ** option_genre Area the option effects; STOptionGenre.
42 ** default_value The default value for the option.
43 ** array_size Used to size a string array.
44 ** multiplier Some numbers prefer conversion.
45 ** option_help Help text to explain the option.
47 ** NOTE! that the multiplier should be applied to the default value if you
48 ** are going to assign the default_value into anything.
50 ** Be very aware that adding things to a particular genre, or adding a genre,
51 ** may completely screw up the caching algorithms of SpaceTrace.
52 ** See contextLookup() or ask someone that knows if you are in doubt.
54 ** The actual definition of the WEB and CMD macros however is left to the
56 ** We cover those that you do not define herein.
58 #if !defined(ST_CMD_OPTION_BOOL)
59 #define ST_CMD_OPTION_BOOL(option_name, option_genre, option_help)
61 #if !defined(ST_WEB_OPTION_BOOL)
62 #define ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
64 #if !defined(ST_CMD_OPTION_STRING)
65 #define ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help)
67 #if !defined(ST_WEB_OPTION_STRING)
68 #define ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
70 #if !defined(ST_CMD_OPTION_STRING_ARRAY)
71 #define ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
73 #if !defined(ST_WEB_OPTION_STRING_ARRAY)
74 #define ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
76 #if !defined(ST_CMD_OPTION_STRING_PTR_ARRAY)
77 #define ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
79 #if !defined(ST_WEB_OPTION_STRING_PTR_ARRAY)
80 #define ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
82 #if !defined(ST_CMD_OPTION_UINT32)
83 #define ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
85 #if !defined(ST_WEB_OPTION_UINT32)
86 #define ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
88 #if !defined(ST_CMD_OPTION_UINT64)
89 #define ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
91 #if !defined(ST_WEB_OPTION_UINT64)
92 #define ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
96 ** ALL macros expand to both CMD and WEB macros.
97 ** This basically means such options are accessible from both the command
98 ** line and from the web options.
100 #define ST_ALL_OPTION_BOOL(option_name, option_genre, option_help) \
101 ST_CMD_OPTION_BOOL(option_name, option_genre, option_help) \
102 ST_WEB_OPTION_BOOL(option_name, option_genre, option_help)
103 #define ST_ALL_OPTION_STRING(option_name, option_genre, default_value, option_help) \
104 ST_CMD_OPTION_STRING(option_name, option_genre, default_value, option_help) \
105 ST_WEB_OPTION_STRING(option_name, option_genre, default_value, option_help)
106 #define ST_ALL_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
107 ST_CMD_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help) \
108 ST_WEB_OPTION_STRING_ARRAY(option_name, option_genre, array_size, option_help)
109 #define ST_ALL_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
110 ST_CMD_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help) \
111 ST_WEB_OPTION_STRING_PTR_ARRAY(option_name, option_genre, option_help)
112 #define ST_ALL_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
113 ST_CMD_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help) \
114 ST_WEB_OPTION_UINT32(option_name, option_genre, default_value, multiplier, option_help)
115 #define ST_ALL_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
116 ST_CMD_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help) \
117 ST_WEB_OPTION_UINT64(option_name, option_genre, default_value, multiplier, option_help)
121 /****************************************************************************
122 ** BEGIN, THE OPTIONS
124 ** Order is somewhat relevant in that it will control 3 different things:
125 ** 1) The order the members will be in the options structure.
126 ** 2) The order the options are presented on the command line.
127 ** 3) The order the options are presented on the web options page.
130 ST_ALL_OPTION_STRING(CategoryName
,
132 ST_ROOT_CATEGORY_NAME
,
133 "Specify a category for reports to focus upon.\n"
134 "See http://lxr.mozilla.org/mozilla/source/tools/trace-malloc/rules.txt\n")
136 ST_ALL_OPTION_UINT32(OrderBy
,
138 ST_SIZE
, /* for dp :-D */
140 "Determine the sort order.\n"
141 "0 by weight (size * lifespan).\n"
144 "3 by allocation count.\n"
145 "4 by performance cost.\n")
147 ST_ALL_OPTION_STRING_ARRAY(RestrictText
,
149 ST_SUBSTRING_MATCH_MAX
,
150 "Exclude allocations which do not have this text in their backtrace.\n"
151 "Multiple restrictions are treated as a logical AND operation.\n")
153 ST_ALL_OPTION_UINT32(SizeMin
,
157 "Exclude allocations that are below this byte size.\n")
159 ST_ALL_OPTION_UINT32(SizeMax
,
163 "Exclude allocations that are above this byte size.\n")
165 ST_ALL_OPTION_UINT32(LifetimeMin
,
167 ST_DEFAULT_LIFETIME_MIN
,
168 ST_TIMEVAL_RESOLUTION
,
169 "Allocations must live this number of seconds or be ignored.\n")
171 ST_ALL_OPTION_UINT32(LifetimeMax
,
173 ST_TIMEVAL_MAX
/ ST_TIMEVAL_RESOLUTION
,
174 ST_TIMEVAL_RESOLUTION
,
175 "Allocations living longer than this number of seconds will be ignored.\n")
177 ST_ALL_OPTION_UINT32(TimevalMin
,
180 ST_TIMEVAL_RESOLUTION
,
181 "Allocations existing solely before this second will be ignored.\n"
182 "Live allocations at this second and after can be considered.\n")
184 ST_ALL_OPTION_UINT32(TimevalMax
,
186 ST_TIMEVAL_MAX
/ ST_TIMEVAL_RESOLUTION
,
187 ST_TIMEVAL_RESOLUTION
,
188 "Allocations existing solely after this second will be ignored.\n"
189 "Live allocations at this second and before can be considered.\n")
191 ST_ALL_OPTION_UINT32(AllocationTimevalMin
,
194 ST_TIMEVAL_RESOLUTION
,
195 "Live and dead allocations created before this second will be ignored.\n")
197 ST_ALL_OPTION_UINT32(AllocationTimevalMax
,
199 ST_TIMEVAL_MAX
/ ST_TIMEVAL_RESOLUTION
,
200 ST_TIMEVAL_RESOLUTION
,
201 "Live and dead allocations created after this second will be ignored.\n")
203 ST_ALL_OPTION_UINT32(AlignBy
,
205 ST_DEFAULT_ALIGNMENT_SIZE
,
207 "All allocation sizes are made to be a multiple of this number.\n"
208 "Closer to actual heap conditions; set to 1 for true sizes.\n")
210 ST_ALL_OPTION_UINT32(Overhead
,
212 ST_DEFAULT_OVERHEAD_SIZE
,
214 "After alignment, all allocations are made to increase by this number.\n"
215 "Closer to actual heap conditions; set to 0 for true sizes.\n")
217 ST_ALL_OPTION_UINT32(ListItemMax
,
221 "Specifies the maximum number of list items to present in each list.\n")
223 ST_ALL_OPTION_UINT64(WeightMin
,
227 "Exclude allocations that are below this weight (lifespan * size).\n")
229 ST_ALL_OPTION_UINT64(WeightMax
,
231 (0xFFFFFFFFLL
<< 32) + 0xFFFFFFFFLL
,
233 "Exclude allocations that are above this weight (lifespan * size).\n")
235 ST_CMD_OPTION_STRING(FileName
,
238 "Specifies trace-malloc input file.\n"
239 "\"-\" indicates stdin will be used as input.\n")
241 ST_CMD_OPTION_STRING(CategoryFile
,
244 "Specifies the category rules file.\n"
245 "This file contains rules about how to categorize allocations.\n")
248 ST_CMD_OPTION_UINT32(HttpdPort
,
252 "Specifies the default port the web server will listen on.\n")
254 ST_CMD_OPTION_STRING(OutputDir
,
257 "Specifies a directory to output batch mode requests.\n"
258 "The directory must exist and must not use a trailing slash.\n")
260 ST_CMD_OPTION_STRING_PTR_ARRAY(BatchRequest
,
262 "This implicitly turns on batch mode.\n"
263 "Save each requested file into the output dir, then exit.\n")
265 ST_CMD_OPTION_UINT32(Contexts
,
269 "How many configurations to cache at the cost of a lot of memory.\n"
270 "Dedicated servers can cache more client configurations for performance.\n")
272 ST_CMD_OPTION_BOOL(Help
,
274 "Show command line help.\n"
275 "See http://www.mozilla.org/projects/footprint/spaceTrace.html\n")
279 ****************************************************************************/
282 ** Everything is undefined after the header is included.
283 ** This sets it up for multiple inclusion if so desired.
285 #undef ST_ALL_OPTION_BOOL
286 #undef ST_CMD_OPTION_BOOL
287 #undef ST_WEB_OPTION_BOOL
288 #undef ST_ALL_OPTION_STRING
289 #undef ST_CMD_OPTION_STRING
290 #undef ST_WEB_OPTION_STRING
291 #undef ST_ALL_OPTION_STRING_ARRAY
292 #undef ST_CMD_OPTION_STRING_ARRAY
293 #undef ST_WEB_OPTION_STRING_ARRAY
294 #undef ST_ALL_OPTION_STRING_PTR_ARRAY
295 #undef ST_CMD_OPTION_STRING_PTR_ARRAY
296 #undef ST_WEB_OPTION_STRING_PTR_ARRAY
297 #undef ST_ALL_OPTION_UINT32
298 #undef ST_CMD_OPTION_UINT32
299 #undef ST_WEB_OPTION_UINT32
300 #undef ST_ALL_OPTION_UINT64
301 #undef ST_CMD_OPTION_UINT64
302 #undef ST_WEB_OPTION_UINT64