...

Source file src/runtime/coverage/apis.go

Documentation: runtime/coverage

     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
     6  
     7  import (
     8  	"fmt"
     9  	"internal/coverage"
    10  	"io"
    11  	"sync/atomic"
    12  	"unsafe"
    13  )
    14  
    15  // WriteMetaDir writes a coverage meta-data file for the currently
    16  // running program to the directory specified in 'dir'. An error will
    17  // be returned if the operation can't be completed successfully (for
    18  // example, if the currently running program was not built with
    19  // "-cover", or if the directory does not exist).
    20  func WriteMetaDir(dir string) error {
    21  	if !finalHashComputed {
    22  		return fmt.Errorf("error: no meta-data available (binary not built with -cover?)")
    23  	}
    24  	return emitMetaDataToDirectory(dir, getCovMetaList())
    25  }
    26  
    27  // WriteMeta writes the meta-data content (the payload that would
    28  // normally be emitted to a meta-data file) for the currently running
    29  // program to the writer 'w'. An error will be returned if the
    30  // operation can't be completed successfully (for example, if the
    31  // currently running program was not built with "-cover", or if a
    32  // write fails).
    33  func WriteMeta(w io.Writer) error {
    34  	if w == nil {
    35  		return fmt.Errorf("error: nil writer in WriteMeta")
    36  	}
    37  	if !finalHashComputed {
    38  		return fmt.Errorf("error: no meta-data available (binary not built with -cover?)")
    39  	}
    40  	ml := getCovMetaList()
    41  	return writeMetaData(w, ml, cmode, cgran, finalHash)
    42  }
    43  
    44  // WriteCountersDir writes a coverage counter-data file for the
    45  // currently running program to the directory specified in 'dir'. An
    46  // error will be returned if the operation can't be completed
    47  // successfully (for example, if the currently running program was not
    48  // built with "-cover", or if the directory does not exist). The
    49  // counter data written will be a snapshot taken at the point of the
    50  // call.
    51  func WriteCountersDir(dir string) error {
    52  	if cmode != coverage.CtrModeAtomic {
    53  		return fmt.Errorf("WriteCountersDir invoked for program built with -covermode=%s (please use -covermode=atomic)", cmode.String())
    54  	}
    55  	return emitCounterDataToDirectory(dir)
    56  }
    57  
    58  // WriteCounters writes coverage counter-data content for the
    59  // currently running program to the writer 'w'. An error will be
    60  // returned if the operation can't be completed successfully (for
    61  // example, if the currently running program was not built with
    62  // "-cover", or if a write fails). The counter data written will be a
    63  // snapshot taken at the point of the invocation.
    64  func WriteCounters(w io.Writer) error {
    65  	if w == nil {
    66  		return fmt.Errorf("error: nil writer in WriteCounters")
    67  	}
    68  	if cmode != coverage.CtrModeAtomic {
    69  		return fmt.Errorf("WriteCounters invoked for program built with -covermode=%s (please use -covermode=atomic)", cmode.String())
    70  	}
    71  	// Ask the runtime for the list of coverage counter symbols.
    72  	cl := getCovCounterList()
    73  	if len(cl) == 0 {
    74  		return fmt.Errorf("program not built with -cover")
    75  	}
    76  	if !finalHashComputed {
    77  		return fmt.Errorf("meta-data not written yet, unable to write counter data")
    78  	}
    79  
    80  	pm := getCovPkgMap()
    81  	s := &emitState{
    82  		counterlist: cl,
    83  		pkgmap:      pm,
    84  	}
    85  	return s.emitCounterDataToWriter(w)
    86  }
    87  
    88  // ClearCounters clears/resets all coverage counter variables in the
    89  // currently running program. It returns an error if the program in
    90  // question was not built with the "-cover" flag. Clearing of coverage
    91  // counters is also not supported for programs not using atomic
    92  // counter mode (see more detailed comments below for the rationale
    93  // here).
    94  func ClearCounters() error {
    95  	cl := getCovCounterList()
    96  	if len(cl) == 0 {
    97  		return fmt.Errorf("program not built with -cover")
    98  	}
    99  	if cmode != coverage.CtrModeAtomic {
   100  		return fmt.Errorf("ClearCounters invoked for program built with -covermode=%s (please use -covermode=atomic)", cmode.String())
   101  	}
   102  
   103  	// Implementation note: this function would be faster and simpler
   104  	// if we could just zero out the entire counter array, but for the
   105  	// moment we go through and zero out just the slots in the array
   106  	// corresponding to the counter values. We do this to avoid the
   107  	// following bad scenario: suppose that a user builds their Go
   108  	// program with "-cover", and that program has a function (call it
   109  	// main.XYZ) that invokes ClearCounters:
   110  	//
   111  	//     func XYZ() {
   112  	//       ... do some stuff ...
   113  	//       coverage.ClearCounters()
   114  	//       if someCondition {   <<--- HERE
   115  	//         ...
   116  	//       }
   117  	//     }
   118  	//
   119  	// At the point where ClearCounters executes, main.XYZ has not yet
   120  	// finished running, thus as soon as the call returns the line
   121  	// marked "HERE" above will trigger the writing of a non-zero
   122  	// value into main.XYZ's counter slab. However since we've just
   123  	// finished clearing the entire counter segment, we will have lost
   124  	// the values in the prolog portion of main.XYZ's counter slab
   125  	// (nctrs, pkgid, funcid). This means that later on at the end of
   126  	// program execution as we walk through the entire counter array
   127  	// for the program looking for executed functions, we'll zoom past
   128  	// main.XYZ's prolog (which was zero'd) and hit the non-zero
   129  	// counter value corresponding to the "HERE" block, which will
   130  	// then be interpreted as the start of another live function.
   131  	// Things will go downhill from there.
   132  	//
   133  	// This same scenario is also a potential risk if the program is
   134  	// running on an architecture that permits reordering of
   135  	// writes/stores, since the inconsistency described above could
   136  	// arise here. Example scenario:
   137  	//
   138  	//     func ABC() {
   139  	//       ...                    // prolog
   140  	//       if alwaysTrue() {
   141  	//         XYZ()                // counter update here
   142  	//       }
   143  	//     }
   144  	//
   145  	// In the instrumented version of ABC, the prolog of the function
   146  	// will contain a series of stores to the initial portion of the
   147  	// counter array to write number-of-counters, pkgid, funcid. Later
   148  	// in the function there is also a store to increment a counter
   149  	// for the block containing the call to XYZ(). If the CPU is
   150  	// allowed to reorder stores and decides to issue the XYZ store
   151  	// before the prolog stores, this could be observable as an
   152  	// inconsistency similar to the one above. Hence the requirement
   153  	// for atomic counter mode: according to package atomic docs,
   154  	// "...operations that happen in a specific order on one thread,
   155  	// will always be observed to happen in exactly that order by
   156  	// another thread". Thus we can be sure that there will be no
   157  	// inconsistency when reading the counter array from the thread
   158  	// running ClearCounters.
   159  
   160  	for _, c := range cl {
   161  		sd := unsafe.Slice((*atomic.Uint32)(unsafe.Pointer(c.Counters)), int(c.Len))
   162  		for i := 0; i < len(sd); i++ {
   163  			// Skip ahead until the next non-zero value.
   164  			sdi := sd[i].Load()
   165  			if sdi == 0 {
   166  				continue
   167  			}
   168  			// We found a function that was executed; clear its counters.
   169  			nCtrs := sdi
   170  			for j := 0; j < int(nCtrs); j++ {
   171  				sd[i+coverage.FirstCtrOffset+j].Store(0)
   172  			}
   173  			// Move to next function.
   174  			i += coverage.FirstCtrOffset + int(nCtrs) - 1
   175  		}
   176  	}
   177  	return nil
   178  }
   179  

View as plain text