coverage.go

     1  // Copyright 2022 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  // Package coverage contains APIs for writing coverage profile data at runtime
     6  // from long-running and/or server programs that do not terminate via [os.Exit].
     7  package coverage
     8  
     9  import (
    10  	"internal/coverage/cfile"
    11  	"io"
    12  )
    13  
    14  // initHook is invoked from main.init in programs built with -cover.
    15  // The call is emitted by the compiler.
    16  func initHook(istest bool) {
    17  	cfile.InitHook(istest)
    18  }
    19  
    20  // WriteMetaDir writes a coverage meta-data file for the currently
    21  // running program to the directory specified in 'dir'. An error will
    22  // be returned if the operation can't be completed successfully (for
    23  // example, if the currently running program was not built with
    24  // "-cover", or if the directory does not exist).
    25  func WriteMetaDir(dir string) error {
    26  	return cfile.WriteMetaDir(dir)
    27  }
    28  
    29  // WriteMeta writes the meta-data content (the payload that would
    30  // normally be emitted to a meta-data file) for the currently running
    31  // program to the writer 'w'. An error will be returned if the
    32  // operation can't be completed successfully (for example, if the
    33  // currently running program was not built with "-cover", or if a
    34  // write fails).
    35  func WriteMeta(w io.Writer) error {
    36  	return cfile.WriteMeta(w)
    37  }
    38  
    39  // WriteCountersDir writes a coverage counter-data file for the
    40  // currently running program to the directory specified in 'dir'. An
    41  // error will be returned if the operation can't be completed
    42  // successfully (for example, if the currently running program was not
    43  // built with "-cover", or if the directory does not exist). The
    44  // counter data written will be a snapshot taken at the point of the
    45  // call.
    46  func WriteCountersDir(dir string) error {
    47  	return cfile.WriteCountersDir(dir)
    48  }
    49  
    50  // WriteCounters writes coverage counter-data content for the
    51  // currently running program to the writer 'w'. An error will be
    52  // returned if the operation can't be completed successfully (for
    53  // example, if the currently running program was not built with
    54  // "-cover", or if a write fails). The counter data written will be a
    55  // snapshot taken at the point of the invocation.
    56  func WriteCounters(w io.Writer) error {
    57  	return cfile.WriteCounters(w)
    58  }
    59  
    60  // ClearCounters clears/resets all coverage counter variables in the
    61  // currently running program. It returns an error if the program in
    62  // question was not built with the "-cover" flag. Clearing of coverage
    63  // counters is also not supported for programs not using atomic
    64  // counter mode (see more detailed comments below for the rationale
    65  // here).
    66  func ClearCounters() error {
    67  	return cfile.ClearCounters()
    68  }
    69
View as plain text