295
edits
Nasal library/debug: Difference between revisions
Jump to navigation
Jump to search
→Class Breakpoint (available since 2019.1)
m (Add warning regarding dump to breakpoint.new) |
|||
| Line 344: | Line 344: | ||
}} | }} | ||
== Class Breakpoint (available since 2019.1) == | == Class Probe (available since 2019.1, upgraded 2020.1) == | ||
The breakpoint class is for selective backtracing. Putting a debug.backtrace() into some nasal code could flood the console / log especially if you do not (yet) know where that code is used. | The probe class can help to finde hot spots in Nasal code by collecting statistics. | ||
It is controlled via the property tree, so you can use it via the property browser. | |||
Data can be viewed / modified in the prop tree /_debug/nas/probe-<myLabel>/* | |||
{{note|New in 2020.1: | |||
Tracing support allows you to see the backtrace in the property tree after a hit. You can see the filenames and line numbers an how often the were hit.}} | |||
=== new() === | |||
{{Nasal doc | |||
|syntax = debug.Probe.new(label, [class = "probe"]); | |||
|text = create a debug.Probe object | |||
|param1 = label | |||
|param1text = A string to name the probe, used in property path and in output. | |||
|param2 = class | |||
|param2text = Used to identify derived classes (see Breakpoint below), used in prop. path | |||
|example1 = var myProbe = debug.Probe.new("myLabel"); | |||
}} | |||
=== enable() === | |||
{{Nasal doc | |||
|syntax = myProbe.enable(); | |||
|text = enable counting (and record start time | |||
}} | |||
=== disable() === | |||
{{Nasal doc | |||
|syntax = myProbe.disable(); | |||
|text = Disable counting, record stop time and generate stats. | |||
}} | |||
=== getHits() === | |||
{{Nasal doc | |||
|syntax = myProbe.getHits(); | |||
|text = Get total number of hits. | |||
}} | |||
=== addCounter() === | |||
{{Nasal doc | |||
|syntax = var id = myProbe.addCounter(); | |||
|text = Creates another counter, selectable as hit(id) | |||
}} | |||
=== hit() === | |||
{{Nasal doc | |||
|syntax = myProbe.hit([counter_id=0][,callback = nil]); | |||
|text = Put this at the place in your code where you want to do the trace. | |||
|param1 = counter_id | |||
|param1text = Number of counter as returned by addCounter(), defaults to 0 | |||
|param2 = callback | |||
|param2text = Optional: on hit call callback(hit_count); | |||
}} | |||
=== reset() === | |||
{{Nasal doc | |||
|syntax = myProbe.reset(); | |||
|text = Reset counter to zero and start time current time. | |||
}} | |||
=== setTimeout(seconds) === | |||
{{Nasal doc | |||
|syntax = myProbe.setTimeout(seconds); | |||
|text = Set timeout. Next hit() after timeout will disable() | |||
}} | |||
=== enableTracing() === | |||
{{Nasal doc | |||
|syntax = myProbe.enableTracing(); | |||
|text = Enable tracing. | |||
}} | |||
=== disableTracing() === | |||
{{Nasal doc | |||
|syntax = myProbe.disableTracing(); | |||
|text = Disable tracing. | |||
}} | |||
== Class Breakpoint (available since 2019.1, upgraded 2020.1) == | |||
The breakpoint class is for selective backtracing. It is derived from the debug.Probe class (see above) and thus supports the same methods unless overridden (see below). | |||
Putting a debug.backtrace() into some nasal code could flood the console / log especially if you do not (yet) know where that code is used. | |||
Using a breakpoint gives you better control when to do backtraces and how often via the property browser at runtime. | Using a breakpoint gives you better control when to do backtraces and how often via the property browser at runtime. | ||
You have to give "tokens" to you breakpoint which are consumed on each hit of the breakpoint, one per trace. No more tokens, no more traces done until you give more tokens. | You have to give "tokens" to you breakpoint which are consumed on each hit of the breakpoint, one per trace. No more tokens, no more traces done until you give more tokens. | ||
| Line 355: | Line 429: | ||
Set tokens to a positive integer to start tracing. Each hit will consume one token and perform one backtrace. | Set tokens to a positive integer to start tracing. Each hit will consume one token and perform one backtrace. | ||
To start tracing again, just set tokens again to the number of traces you wish to perform. | To start tracing again, just set tokens again to the number of traces you wish to perform. | ||
{{note| Tracing support was added in version 2020.1, see Probe class above }} | |||
=== new() === | === new() === | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = Breakpoint.new(label, | |syntax = Breakpoint.new(label [,dump_locals = 1][,skip_level=0]); | ||
|text = create a breakpoint object | |text = create a breakpoint object | ||
|param1 = label | |param1 = label | ||
| Line 364: | Line 440: | ||
|param2 = dump_locals | |param2 = dump_locals | ||
|param2text = 0 or 1, passed to backtrace to control printing of namespaces (variables). Warning: dumping big namespaces can cause a stack overflow and crash the nasal script. | |param2text = 0 or 1, passed to backtrace to control printing of namespaces (variables). Warning: dumping big namespaces can cause a stack overflow and crash the nasal script. | ||
|param3 = skip_level | |||
|param3text = passed to debug.backtrace to skip the first n levels in the bt. | |||
|example1 = var myBP = debug.Breakpoint.new("myLabel", 0); | |example1 = var myBP = debug.Breakpoint.new("myLabel", 0); | ||
}} | }} | ||
=== enable() === | === enable() === | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = myBP.enable([tokens = 1]); | |syntax = myBP.enable([tokens = 1]); | ||
|text = | |text = Start tracing | ||
|param1 = tokens | |param1 = tokens | ||
|param1text = Number of traces allowed; each hit will consume one token, tokens < 1 means no more traces. Tokens can be also set via the property browser at runtime. | |param1text = Number of traces allowed; each hit will consume one token, tokens < 1 means no more traces. Tokens can be also set via the property browser at runtime. | ||
}} | }} | ||
=== hit() === | === hit() === | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = myBP.hit(); | |syntax = myBP.hit([callback]); | ||
|text = Put this at the place in your code where you want to do the trace. | |text = Put this at the place in your code where you want to do the trace. | ||
|param1 = callback | |||
|param1text = Optional: function to call instread of debug.backtrace. It will be called as callback(number_of_hits, remaining_tokens); | |||
}} | }} | ||
{{Nasal namespaces}} | {{Nasal namespaces}} | ||