diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/reference/futures-logging.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/reference/futures-logging.scrbl index f72b3ee9cb..669f302c43 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/reference/futures-logging.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/reference/futures-logging.scrbl @@ -12,7 +12,7 @@ code via @racket[trace-futures]), it is much easier to use the graphical profiler tool provided by @racketmodname[future-visualizer]. -Future events are reported to a logger named @racket['future]. +Future events are logged with the topic @racket['future]. In addition to its string message, each event logged for a future has a data value that is an instance of a @racket[future-event] @tech{prefab} structure: diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/reference/logging.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/reference/logging.scrbl index e5fc3444c0..22ef657dfb 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/reference/logging.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/reference/logging.scrbl @@ -8,18 +8,17 @@ A @deftech{logger} accepts events that contain information to be logged for interested parties. A @deftech{log receiver} represents an interested party that receives logged events asynchronously. Each -event has a level of importance, and a @tech{log receiver} subscribes to -logging events at a certain level of importance and higher. The -levels, in decreasing order of importance, are @racket['fatal], +event has a topic and level of detail, and a @tech{log receiver} subscribes to +logging events at a certain level of detail (and higher) for a specific topic or for all topics. The +levels, in increasing order of detail, are @racket['fatal], @racket['error], @racket['warning], @racket['info], and @racket['debug]. -To help organize logged events, @tech{loggers} can be named and -hierarchical. Every event reported to a logger is also propagated to -its parent (if any), but the event message is prefixed with a name (if -any) that is typically the name of the logger to which is was -originally reported. A logger is not required to have a parent or -name. +To help organize logged events, a @tech{logger} can have a default topic and/or +a parent logger. Every event reported to a logger is also propagated to +its parent (if any), while the event message is prefixed with the logger's topic (if +any) if the message does already have a topic. Furthermore, events that are propagated +from a logger to its parent can be filtered by level and topic. On start-up, Racket creates an initial logger that is used to record events from the core run-time system. For example, an @@ -44,13 +43,13 @@ through environment variables: events the corresponding level of higher are printed. After an initial @nonterm{level}, the value can contain space-separated specifications of the form - @nonterm{level}@litchar["@"]@nonterm{name}, which prints events - whose names match @nonterm{name} only at the given - @nonterm{level} or higher (where a @nonterm{name} contains any + @nonterm{level}@litchar["@"]@nonterm{topic}, which prints events + whose topics match @nonterm{topic} only at the given + @nonterm{level} or higher (where a @nonterm{topic} contains any character other than a space or @litchar["@"]). For example, the value @racket["error debug@GC"] prints all events at the - @racket['error] level and higher, but prints events - named @racket['GC] at the @racket['debug] level and + @racket['error] level and higher, but prints events for the topic + topic @racket['GC] at the @racket['debug] level and higher (which includes all levels). The default is @racket["error"].} @@ -83,16 +82,16 @@ Returns @racket[#t] if @racket[v] is a @tech{logger}, @racket[#f] otherwise.} -@defproc[(make-logger [name (or/c symbol? #f) #f] +@defproc[(make-logger [topic (or/c symbol? #f) #f] [parent (or/c logger? #f) #f] [propagate-level (or/c 'none 'fatal 'error 'warning 'info 'debug) 'debug] - [propagate-name (or/c #f symbol?) #f] + [propagate-topic (or/c #f symbol?) #f] ... ...) logger?]{ -Creates a new @tech{logger} with an optional name and parent. +Creates a new @tech{logger} with an optional topic and parent. -The optional @racket[propagate-level] and @racket[propagate-name] +The optional @racket[propagate-level] and @racket[propagate-topic] arguments constrain the events that are propagated from the new logger to @racket[parent] (when @racket[parent] is not @racket[#f]) in the same way that events are described for a log receiver in @@ -102,18 +101,20 @@ same way that events are described for a log receiver in @history[#:changed "6.1.1.3" @elem{Removed an optional argument to specify a notification callback, and added @racket[propagate-level] and - @racket[propagate-name] constraints for + @racket[propagate-topic] constraints for events to propagate.}]} @defproc[(logger-name [logger logger?]) (or/c symbol? #f)]{ -Reports @racket[logger]'s name, if any.} +Reports @racket[logger]'s default topic, if any.} + @defparam[current-logger logger logger?]{ A @tech{parameter} that determines the @tech{current logger}.} + @defform[(define-logger id)]{ Defines @racketkeywordfont{log-}@racket[id]@racketkeywordfont{-fatal}, @@ -123,8 +124,8 @@ Defines @racketkeywordfont{log-}@racket[id]@racketkeywordfont{-fatal}, @racketkeywordfont{log-}@racket[id]@racketkeywordfont{-debug} as forms like @racket[log-fatal], @racket[log-error],@racket[log-warning], @racket[log-info], and @racket[log-debug]. The @racket[define-logger] -form also defines @racket[id]@racketidfont{-logger}, which is a logger named -@racket['@#,racket[id]] that is a child of @racket[(current-logger)]; +form also defines @racket[id]@racketidfont{-logger}, which is a logger with +default topic @racket['@#,racket[id]] that is a child of @racket[(current-logger)]; the @racketkeywordfont{log-}@racket[id]@racketkeywordfont{-fatal}, @|etc| forms use this new logger. The new logger is created when @racket[define-logger] is evaluated.} @@ -134,7 +135,7 @@ created when @racket[define-logger] is evaluated.} @defproc[(log-message [logger logger?] [level (or/c 'fatal 'error 'warning 'info 'debug)] - [name (or/c symbol? #f) (object-name logger)] + [topic (or/c symbol? #f) (logger-name logger)] [message string?] [data any/c] [prefix-message? any/c #t]) @@ -145,9 +146,9 @@ information to any @tech{log receivers} attached to @racket[logger] or its ancestors that are interested in events at @racket[level] or higher. -@tech{Log receivers} can filter events based on @racket[name]. In -addition, if @racket[name] and @racket[prefix-message?] are not -@racket[#f], then @racket[message] is prefixed with the name followed +@tech{Log receivers} can filter events based on @racket[topic]. In +addition, if @racket[topic] and @racket[prefix-message?] are not +@racket[#f], then @racket[message] is prefixed with the topic followed by @racket[": "] before it is sent to receivers. @history[#:changed "6.0.1.10" @elem{Added the @racket[prefix-message?] argument.}]} @@ -155,14 +156,14 @@ by @racket[": "] before it is sent to receivers. @defproc[(log-level? [logger logger?] [level (or/c 'fatal 'error 'warning 'info 'debug)] - [name (or/c symbol? #f) #f]) + [topic (or/c symbol? #f) #f]) boolean?]{ Reports whether any @tech{log receiver} attached to @racket[logger] or one of its ancestors is interested in @racket[level] events (or -potentially lower) or @racket[name]. If @racket[name] is @racket[#f], +potentially lower) for @racket[topic]. If @racket[topic] is @racket[#f], the result indicates whether a @tech{log receiver} is interested in -events at @racket[level] for any name. +events at @racket[level] for any topic. Use this function to avoid work generating an event for @racket[log-message] if no receiver is interested in the @@ -175,19 +176,19 @@ The result of this function can change if a garbage collection determines that a log receiver is no longer accessible (and therefore that any event information it receives will never become accessible). -@history[#:changed "6.1.1.3" @elem{Added the @racket[name] argument.}]} +@history[#:changed "6.1.1.3" @elem{Added the @racket[topic] argument.}]} @defproc[(log-max-level [logger logger?] - [name (or/c symbol? #f) #f]) + [topic (or/c symbol? #f) #f]) (or/c #f 'fatal 'error 'warning 'info 'debug)]{ -Similar to @racket[log-level?], but reports the maximum level of logging for -which @racket[log-level?] on @racket[logger] and @racket[name] returns @racket[#t]. The -result is @racket[#f] if @racket[log-level?] with @racket[logger] +Similar to @racket[log-level?], but reports the maximum-detail level of logging for +which @racket[log-level?] on @racket[logger] and @racket[topic] returns @racket[#t]. The +result is @racket[#f] if @racket[log-level?] with @racket[logger] and @racket[topic] currently returns @racket[#f] for all levels. -@history[#:changed "6.1.1.3" @elem{Added the @racket[name] argument.}]} +@history[#:changed "6.1.1.3" @elem{Added the @racket[topic] argument.}]} @defproc[(log-all-levels [logger logger?]) @@ -199,16 +200,15 @@ Summarizes the possible results of @racket[log-max-level] on all possible @tech{interned} symbols. The result list contains a sequence of symbols and @racket[#f], where the first, third, etc., list element corresponds to a level, and the second, fourth, etc., list element -indicates a corresponding name. The level is the result that -@racket[log-max-level] would produce for the name, where the level for -the @racket[#f] name (which is always present in the result list) -indicates the result for any @tech{interned}-symbol name that does not +indicates a corresponding topic. The level is the result that +@racket[log-max-level] would produce for the topic, where the level for +the @racket[#f] topic (which is always present in the result list) +indicates the result for any @tech{interned}-symbol topic that does not appear in the list. The result is suitable as a sequence of arguments to -@racket[make-log-receiver] (after a @tech{logger} argument). Combining -the arguments with @racket[logger] creates a new receiver for only -events that already have other receivers. +@racket[make-log-receiver] (after a @tech{logger} argument) to create +a new receiver for events that currently have receivers in @racket[logger]. @history[#:added "6.1.1.4"]} @@ -225,8 +225,8 @@ The condition reported by the event is a conservative approximation: the event can become @tech{ready for synchronization} even if the results of @racket[log-level?], @racket[log-max-level], and @racket[log-all-levels] are unchanged. Nevertheless, the expectation -is that events become ready infrequently, because they are triggered -byt the creation of a log receiver. +is that events produced by @racket[log-level-evt] become ready infrequently, +because they are triggered by the creation of a log receiver. @history[#:added "6.1.1.4"]} @@ -251,7 +251,7 @@ addition, the current continuation's @tech{continuation marks} are sent to the logger with the message string. These form are convenient for using the current logger, but libraries -should generally use a specifically named logger---typically through +should generally use a logger for a specific topic---typically through similar convenience forms generated by @racket[define-logger]. For each @racketkeywordfont{log-}@racket[_level], @@ -291,14 +291,14 @@ otherwise.} @defproc[(make-log-receiver [logger logger?] [level (or/c 'none 'fatal 'error 'warning 'info 'debug)] - [name (or/c #f symbol?) #f] + [topic (or/c #f symbol?) #f] ... ...) log-receiver?]{ -Creates a @tech{log receiver} to receive events of importance -@racket[level] and higher as reported to @racket[logger] and its -descendants, as long as either @racket[name] is @racket[#f] or the -event's name matches @racket[name]. +Creates a @tech{log receiver} to receive events of detail +@racket[level] and lower as reported to @racket[logger] and its +descendants, as long as either @racket[topic] is @racket[#f] or the +event's topic matches @racket[topic]. A @tech{log receiver} is a @tech{synchronizable event}. It becomes @tech{ready for synchronization} when a logging event is @@ -307,15 +307,13 @@ received, so use @racket[sync] to receive an logged event. The four values: the level of the event as a symbol, an immutable string for the event message, an arbitrary value that was supplied as the last argument to @racket[log-message] when the event was logged, and a -symbol or @racket[#f] for the event name (where a symbol is usually -the name of the original logger for the event). +symbol or @racket[#f] for the event topic. -Multiple pairs of @racket[level] and @racket[name] can be provided to +Multiple pairs of @racket[level] and @racket[topic] can be provided to indicate different specific @racket[level]s for different -@racket[name]s (where @racket[name] defaults to @racket[#f] only for +@racket[topic]s (where @racket[topic] defaults to @racket[#f] only for the last given @racket[level]). A @racket[level] for a @racket[#f] -@racket[name] applies only to events whose names do not match any other -provided @racket[name]. If the same @racket[name] is provided multiple +@racket[topic] applies only to events whose topic does not match any other +provided @racket[topic]. If the same @racket[topic] is provided multiple times, the @racket[level] provided with the last instance in the argument list takes precedence.} - diff --git a/pkgs/racket-pkgs/racket-doc/scribblings/reference/memory.scrbl b/pkgs/racket-pkgs/racket-doc/scribblings/reference/memory.scrbl index 852c4b1dcc..ec2aff18a9 100644 --- a/pkgs/racket-pkgs/racket-doc/scribblings/reference/memory.scrbl +++ b/pkgs/racket-pkgs/racket-doc/scribblings/reference/memory.scrbl @@ -201,7 +201,7 @@ Set the @as-index{@envvar{PLTDISABLEGC}} environment variable (to any value) before Racket starts to disable @tech{garbage collection}. In Racket 3m (the main variant of Racket), each garbage collection -logs a message (see @secref["logging"]) at the @racket['debug] level to a logger named @racket['GC]. +logs a message (see @secref["logging"]) at the @racket['debug] level with topic @racket['GC]. The data portion of the message is an instance of a @indexed-racket[gc-info] @tech{prefab} structure type with 10 fields as follows, but future versions of Racket may use a @racket[gc-info] @tech{prefab} structure