1lcnt(3) Erlang Module Definition lcnt(3)
2
6 lcnt - A runtime system Lock Profiling tool.
7
9 The lcnt module is used to profile the internal ethread locks in the
10 Erlang Runtime System. With lcnt enabled, internal counters in the run‐
11 time system are updated each time a lock is taken. The counters stores
12 information about the number of acquisition tries and the number of
13 collisions that has occurred during the acquisition tries. The counters
14 also record the waiting time a lock has caused for a blocked thread
15 when a collision has occurred.
16 The data produced by the lock counters will give an estimate on how
18 well the runtime system will behave from a parallelizable view point
19 for the scenarios tested. This tool was mainly developed to help Erlang
20 runtime developers iron out potential and generic bottlenecks.
21 Locks in the emulator are named after what type of resource they pro‐
23 tect and where in the emulator they are initialized, those are lock
24 'classes'. Most of those locks are also instantiated several times, and
25 given unique identifiers, to increase locking granularity. Typically an
26 instantiated lock protects a disjunct set of the resource, for example
27 ets tables, processes or ports. In other cases it protects a specific
28 range of a resource, for example pix_lock which protects index to
29 process mappings, and is given a unique number within the class. A
30 unique lock in lcnt is referenced by a name (class) and an identifier:
31 {Name, Id}.
32 Some locks in the system are static and protects global resources, for
34 example bif_timers and the run_queue locks. Other locks are dynamic and
35 not necessarily long lived, for example process locks and ets-table
36 locks. The statistics data from short lived locks can be stored sepa‐
37 rately when the locks are deleted. This behavior is by default turned
38 off to save memory but can be turned on via lcnt:rt_opt({copy_save,
39 true}). The lcnt:apply/1,2,3 functions enables this behavior during
40 profiling.
41
43 start() -> {ok, Pid} | {error, {already_started, Pid}}
44 Types:
46 Pid = pid()
48 Starts the lock profiler server. The server only act as a medium
50 for the user and performs filtering and printing of data col‐
51 lected by lcnt:collect/1.
52 stop() -> ok
54 Stops the lock profiler server.
56 collect() -> ok
58 Same as collect(node()).
60 collect(Node) -> ok
62 Types:
64 Node = node()
66 Collects lock statistics from the runtime system. The function
68 starts a server if it is not already started. It then populates
69 the server with lock statistics. If the server held any lock
70 statistics data before the collect then that data is lost.
71 clear() -> ok
73 Same as clear(node()).
75 clear(Node) -> ok
77 Types:
79 Node = node()
81 Clears the internal lock statistics from the runtime system.
83 This does not clear the data on the server only on runtime sys‐
84 tem. All counters for static locks are zeroed, all dynamic locks
85 currently alive are zeroed and all saved locks now destroyed are
86 removed. It also resets the duration timer.
87 conflicts() -> ok
89 Same as conflicts([]).
91 conflicts(Options) -> ok
93 Types:
95 Options = [option()]
97 option() =
98 {sort, Sort :: sort()} |
99 {reverse, boolean()} |
100 {locations, boolean()} |
101 {thresholds, Thresholds :: [threshold()]} |
102 {print,
103 PrintOptions :: [print() | {print(), integer() >= 0}]} |
104 {max_locks, MaxLocks :: integer() >= 0 | none} |
105 {combine, boolean()}
106 print() =
107 colls | duration | entry | id | name | ratio | time | tries |
108 type
109 sort() =
110 colls | entry | id | name | ratio | time | tries | type
111 threshold() =
112 {colls, integer() >= 0} |
113 {time, integer() >= 0} |
114 {tries, integer() >= 0}
115 Prints a list of internal locks and its statistics.
117 For option description, see lcnt:inspect/2.
119 locations() -> ok
121 Same as locations([]).
123 locations(Options) -> ok
125 Types:
127 Options = [option()]
129 option() =
130 {sort, Sort :: sort()} |
131 {reverse, boolean()} |
132 {locations, boolean()} |
133 {thresholds, Thresholds :: [threshold()]} |
134 {print,
135 PrintOptions :: [print() | {print(), integer() >= 0}]} |
136 {max_locks, MaxLocks :: integer() >= 0 | none} |
137 {combine, boolean()}
138 print() =
139 colls | duration | entry | id | name | ratio | time | tries |
140 type
141 sort() =
142 colls | entry | id | name | ratio | time | tries | type
143 threshold() =
144 {colls, integer() >= 0} |
145 {time, integer() >= 0} |
146 {tries, integer() >= 0}
147 Prints a list of internal lock counters by source code loca‐
149 tions.
150 For option description, see lcnt:inspect/2.
152 inspect(Lock) -> ok
154 Types:
156 Lock = Name | {Name, Id | [Id]}
158 Name = atom() | pid() | port()
159 Id = atom() | integer() | pid() | port()
160 Same as inspect(Lock, []).
162 inspect(Lock, Options) -> ok
164 Types:
166 Lock = Name | {Name, Id | [Id]}
168 Name = atom() | pid() | port()
169 Id = atom() | integer() | pid() | port()
170 Options = [option()]
171 option() =
172 {sort, Sort :: sort()} |
173 {reverse, boolean()} |
174 {locations, boolean()} |
175 {thresholds, Thresholds :: [threshold()]} |
176 {print,
177 PrintOptions :: [print() | {print(), integer() >= 0}]} |
178 {max_locks, MaxLocks :: integer() >= 0 | none} |
179 {combine, boolean()}
180 print() =
181 colls | duration | entry | id | name | ratio | time | tries |
182 type
183 sort() =
184 colls | entry | id | name | ratio | time | tries | type
185 threshold() =
186 {colls, integer() >= 0} |
187 {time, integer() >= 0} |
188 {tries, integer() >= 0}
189 Prints a list of internal lock counters for a specific lock.
191 Lock Name and Id for ports and processes are interchangeable
193 with the use of lcnt:swap_pid_keys/0 and is the reason why pid()
194 and port() options can be used in both Name and Id space. Both
195 pids and ports are special identifiers with stripped creation
196 and can be recreated with lcnt:pid/2,3 and lcnt:port/1,2.
197 Option description:
199 {combine, boolean()}:
201 Combine the statistics from different instances of a lock
202 class.
203 Default: true
204 {locations, boolean()}:
206 Print the statistics by source file and line numbers.
207 Default: false
208 {max_locks, MaxLocks}:
210 Maximum number of locks printed or no limit with none.
211 Default: 20
212 {print, PrintOptions}:
214 Printing options:
215 name:
217 Named lock or named set of locks (classes). The same name
218 used for initializing the lock in the VM.
219 id:
221 Internal id for set of locks, not always unique. This
222 could be table name for ets tables (db_tab), port id for
223 ports, integer identifiers for allocators, etc.
224 type:
226 Type of lock: rw_mutex, mutex, spinlock, rw_spinlock or
227 proclock.
228 entry:
230 In combination with {locations, true} this option prints
231 the lock operations source file and line number entry-
232 points along with statistics for each entry.
233 tries:
235 Number of acquisitions of this lock.
236 colls:
238 Number of collisions when a thread tried to acquire this
239 lock. This is when a trylock is EBUSY, a write try on read
240 held rw_lock, a try read on write held rw_lock, a thread
241 tries to lock an already locked lock. (Internal states su‐
242 pervises this).
243 ratio:
245 The ratio between the number of collisions and the number
246 of tries (acquisitions) in percentage.
247 time:
249 Accumulated waiting time for this lock. This could be
250 greater than actual wall clock time, it is accumulated for
251 all threads. Trylock conflicts does not accumulate time.
252 duration:
254 Percentage of accumulated waiting time of wall clock time.
255 This percentage can be higher than 100% since accumulated
256 time is from all threads.
257 Default: [name,id,tries,colls,ratio,time,duration]
258 {reverse, boolean()}:
260 Reverses the order of sorting.
261 Default: false
262 {sort, Sort}:
264 Column sorting orders.
265 Default: time
266 {thresholds, Thresholds}:
268 Filtering thresholds. Anything values above the threshold
269 value are passed through.
270 Default: [{tries, 0}, {colls, 0}, {time, 0}]
271 information() -> ok
273 Prints lcnt server state and generic information about collected
275 lock statistics.
276 swap_pid_keys() -> ok
278 Swaps places on Name and Id space for ports and processes.
280 load(Filename) -> ok
282 Types:
284 Filename = file:filename()
286 Restores previously saved data to the server.
288 save(Filename) -> ok
290 Types:
292 Filename = file:filename()
294 Saves the collected data to file.
296
298 The following functions are used for convenience.
299
301 apply(Fun) -> term()
302 Types:
304 Fun = function()
306 Same as apply(Fun, []).
308 apply(Fun, Args) -> term()
310 Types:
312 Fun = function()
314 Args = [term()]
315 Clears the lock counters and then setups the instrumentation to
317 save all destroyed locks. After setup the function is called,
318 passing the elements in Args as arguments. When the function re‐
319 turns the statistics are immediately collected to the server.
320 After the collection the instrumentation is returned to its pre‐
321 vious behavior. The result of the applied function is returned.
322 Warning:
324 This function should only be used for micro-benchmarks; it sets
325 copy_save to true for the duration of the call, which can
326 quickly lead to running out of memory.
327 apply(Module, Function, Args) -> term()
330 Types:
332 Module = module()
334 Function = atom()
335 Args = [term()]
336 Same as apply(fun() -> erlang:apply(Module, Function, Args)
338 end).
339 pid(Id, Serial) -> pid()
341 Types:
343 Id = Serial = integer()
345 Same as pid(node(), Id, Serial).
347 pid(Node, Id, Serial) -> pid()
349 Types:
351 Node = node()
353 Id = Serial = integer()
354 Creates a process id with creation 0.
356 port(Id) -> port()
358 Types:
360 Id = integer()
362 Same as port(node(), Id).
364 port(Node, Id) -> port()
366 Types:
368 Node = node()
370 Id = integer()
371 Creates a port id with creation 0.
373
375 The following functions control the behavior of the internal counters.
376
378 rt_collect() -> [lock_counter_data()]
379 Types:
381 lock_counter_data() = term()
383 Same as rt_collect(node()).
385 rt_collect(Node) -> [lock_counter_data()]
387 Types:
389 Node = node()
391 lock_counter_data() = term()
392 Returns a list of raw lock counter data.
394 rt_clear() -> ok
396 Same as rt_clear(node()).
398 rt_clear(Node) -> ok
400 Types:
402 Node = node()
404 Clear the internal counters. Same as lcnt:clear(Node).
406 rt_mask() -> [category_atom()]
408 Types:
410 category_atom() = atom()
412 Same as rt_mask(node()).
414 rt_mask(Node) -> [category_atom()]
416 Types:
418 Node = node()
420 category_atom() = atom()
421 Refer to rt_mask/2. for a list of valid categories. All cate‐
423 gories are enabled by default.
424 rt_mask(Categories) -> ok | {error, copy_save_enabled}
426 Types:
428 Categories = [category_atom()]
430 category_atom() = atom()
431 Same as rt_mask(node(), Categories).
433 rt_mask(Node, Categories) -> ok | {error, copy_save_enabled}
435 Types:
437 Node = node()
439 Categories = [category_atom()]
440 category_atom() = atom()
441 Sets the lock category mask to the given categories.
443 This will fail if the copy_save option is enabled; see
445 lcnt:rt_opt/2.
446 Valid categories are:
448 * allocator
450 * db (ETS tables)
452 * debug
454 * distribution
456 * generic
458 * io
460 * process
462 * scheduler
464 This list is subject to change at any time, as is the category
466 any given lock may belong to.
467 rt_opt(Option) -> boolean()
469 Types:
471 Option = {Type, Value :: boolean()}
473 Type = copy_save | process_locks
474 Same as rt_opt(node(), {Type, Value}).
476 rt_opt(Node, Option) -> boolean()
478 Types:
480 Node = node()
482 Option = {Type, Value :: boolean()}
483 Type = copy_save | process_locks
484 Option description:
486 {copy_save, boolean()}:
488 Retains the statistics of destroyed locks.
489 Default: false
490 Warning:
492 This option will use a lot of memory when enabled, which must
493 be reclaimed with lcnt:rt_clear. Note that it makes no dis‐
494 tinction between locks that were destroyed and locks for which
495 counting was disabled, so enabling this option will disable
496 changes to the lock category mask.
497 {process_locks, boolean()}:
500 Profile process locks, equal to adding process to the lock
501 category mask; see lcnt:rt_mask/2
502 Default: true
503
505 LCNT User's Guide
506Ericsson AB tools 3.6 lcnt(3)