third_party/WebKit/Source/platform/wtf/ScopedLogger.md - Issue 2774333002: Revert "Move files in wtf/ to platform/wtf/"

Side by Side Diff: third_party/WebKit/Source/platform/wtf/ScopedLogger.md

Issue 2774333002: Revert "Move files in wtf/ to platform/wtf/" (Closed)

Patch Set: Created 3 years, 8 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

OLD	NEW
	(Empty)
1 # Debugging with ScopedLogger

2

3 ## Overview

4

5 ScopedLogger is a logger that shows nested calls by indenting.

6

7 For example, if you were debugging a layout issue you could add a ScopedLogger

8 to the top of the `LayoutBlock::layout` function:

9

10 ```c++

11 void LayoutBlock::layout()

12 {

13 WTF_CREATE_SCOPED_LOGGER(logger, "layout %s", debugName().utf8().data());

14 ...

15 ```

16

17 The arguments of the `WTF_CREATE_SCOPED_LOGGER` macro are the name of the

18 object, followed by the first log message, followed by printf-style varargs.

19 In the above example, the log message includes the debug name of the block that

20 is currently being laid out.

21

22 ScopedLogger wraps log messages in parentheses, with indentation proportional to

23 the number of instances. This makes it easy to see the flow of control in the

24 output, particularly when instrumenting recursive functions. Here is some of

25 the output of the above example when laying out www.google.com:

26

27 ```

28 ( layout LayoutView #document

29 ( layout LayoutBlockFlow HTML

30 ( layout LayoutBlockFlow BODY id='gsr' class='hp vasq'

31 ( layout LayoutBlockFlow (relative positioned) DIV id='viewport' class='ct r-p'

32 ( layout LayoutBlockFlow DIV id='doc-info' )

33 ( layout LayoutBlockFlow DIV id='cst' )

34 ( layout LayoutBlockFlow (positioned) A )

35 ( layout LayoutBlockFlow (positioned) DIV id='searchform' class='jhp' )

36 )

37 )

38 )

39 )

40 ```

41

42 ## Appending to a ScopedLogger

43

44 Every ScopedLogger has an initial log message, which is often sufficient. But

45 you can also write additional messages to an existing ScopedLogger with

46 `WTF_APPEND_SCOPED_LOGGER`. For example:

47

48 ```c++

49 // further down in LayoutBlock::layout...

50

51 if (needsScrollAnchoring) {

52 WTF_APPEND_SCOPED_LOGGER(logger, "restoring scroll anchor");

53 getScrollableArea()->scrollAnchor().restore();

54 }

55 ```

56

57 ## Conditional ScopedLoggers

58

59 It's often useful to create a ScopedLogger only if some condition is met.

60 Unfortunately, the following doesn't work correctly:

61

62 ```c++

63 void foo() {

64 if (condition) {

65 WTF_CREATE_SCOPED_LOGGER(logger, "foo, with condition");

66 // Oops: logger exits scope prematurely!

67 }

68 bar(); // any ScopedLogger in bar won't nest

69 }

70 ```

71

72 To guard a ScopedLogger construction with a condition without restricting its

73 scope, use `WTF_CREATE_SCOPED_LOGGER_IF`:

74

75 ```c++

76 void foo() {

77 WTF_CREATE_SCOPED_LOGGER_IF(logger, condition, "message");

78 bar();

79 }

80 ```

81

82 ## Requirements

83

84 The ScopedLogger class and associated macros are defined in

85 [Assertions.h](Assertions.h), which most Blink source files already include

86 indirectly. ScopedLogger can't be used outside of Blink code yet.

87

88 The ScopedLogger macros work in debug builds by default. They are compiled out

89 of release builds, unless your `GYP_DEFINES` or GN args file includes one of the

90 following:

91

92 * `dcheck_always_on`: enables assertions and ScopedLogger

93 * `blink_logging_always_on`: enables ScopedLogger, but not assertions

94

95 The macro names are cumbersome to type, but most editors can be configured to

96 make this easier. For example, you can add the following to a Sublime Text key

97 binding file to make Ctrl+Alt+L insert a ScopedLogger:

98

99 ```

100 { "keys": ["ctrl+alt+l"], "command": "insert",

101 "args": {"characters": "WTF_CREATE_SCOPED_LOGGER(logger, \"msg\");"}

102 }

103 ```

OLD	NEW