.

go/neo/client/client.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package client provides ZODB interface for accessing NEO cluster
+// Package client provides ZODB interface for accessing NEO cluster.
 package client
 
 import (

go/neo/cmd/neo/neo.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Neo is a driver program for running & invoking NEO commands and services
+// Neo is a driver program for running & invoking NEO commands and services.
 package main
 
 import (

go/neo/neo.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package neo and its children provide distributed object storage for ZODB
+// Package neo and its children provide distributed object storage for ZODB.
 //
 // Package neo itself provides protocol definition and common infrastructure.
 // See packages neo.client and neo.server for client and server sides respectively.

go/neo/neotools/doc.go

@@ -17,5 +17,5 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package neotools provides tools for running and managing NEO databases
+// Package neotools provides tools for running and managing NEO databases.
 package neotools

go/neo/server/doc.go

@@ -17,5 +17,5 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package server provides servers side of NEO
+// Package server provides servers side of NEO.
 package server

go/xcommon/tracing/cmd/gotrace/gotrace.go

@@ -18,17 +18,19 @@
 // See https://www.nexedi.com/licensing for rationale and options.
 
 /*
-gotrace TODO
+Gotrace is a program to support and interact with go tracing subsystem.
 
-	gen	generates code according to tracing annotations and imports
-	list	lists tracepoints defined in a package
+Gotrace is a common entry to tracing and provides several subcommands:
 
-gotrace gen package
-gotrace list package	TODO
+	gen	generate code according to tracing annotations and imports
+	list	lists tracepoints defined in a package
 
 XXX tracepoints this package defines
 XXX tracepoints this package imports
 
+See package lab.nexedi.com/kirr/go123/tracing documentation on how to define
+and use trace events in programs. XXX
+
 FIXME build tags not taken into account
 */
 package main
@@ -514,6 +516,7 @@ func {{.ImportSpec.PkgName}}_{{.Name}}_Attach(*tracing.ProbeGroup, func({{.ArgvT
 
 // traceEventImportCheckTmpl is code template generated to check consistency with one imported package
 var traceEventImportCheckTmpl = template.Must(template.New("traceimportcheck").Parse(`
+{{/* linking will fail if trace import code becomes out of sync wrt imported package */ -}}
 // rerun "gotrace gen" if you see link failure ↓↓↓
 //go:linkname {{.ImportSpec.PkgName}}_trace_exporthash {{.ImportSpec.PkgPath}}._trace_exporthash_{{.ExportHash}}
 func {{.ImportSpec.PkgName}}_trace_exporthash()
@@ -897,6 +900,10 @@ func traceExportHash(tpkg *Package, kind string) string {
 	return fmt.Sprintf("%x", sha1.Sum(traceExport(tpkg, kind)))
 }
 
+
+// TODO
+// func tracelist(...)
+
 func main() {
 	log.SetFlags(0)
 	log.SetPrefix("gotrace: ")

go/xcommon/tracing/tracing.go

@@ -18,16 +18,115 @@
 // See https://www.nexedi.com/licensing for rationale and options.
 
 /*
-Package tracing provides runtime and usage support for Go tracing facilities
+Package tracing provides runtime and usage support for Go tracing facilities.
 
-TODO describe how to define tracepoints
-TODO doc:
-- tracepoints
-- probes
-- probes can be attached/detached to/from tracepoints
 
-TODO document //trace:event & //trace:import
+Trace events
+
+A Go package can define several events of interest to trace via special
+comments. With such definition a tracing event becomes associated with trace
+function that is used to signal when the event happens. For example:
+
+	package hello
+
+	//trace:event traceHelloPre(who string)
+	//trace:event traceHello(who string)
+
+	func SayHello(who string) {
+		traceHelloPre(who)
+		fmt.Println("Hello, %s", who)
+		traceHello(who)
+	}
+
+By default trace function does nothing and has very small overhead(*).
+
+
+Probes
+
+However it is possible to attach probing functions to events. A probe, once
+attached, is called whenever event is signalled in the context which triggered
+the event and pauses original code execution until the probe is finished. It is
+possible to attach several probing functions to the same event and dynamically
+detach/(re-)attach them. Attaching/detaching probes must be done under
+tracing.Lock. For example:
+
+	type saidHelloT struct {
+		who  string
+		when time.Time
+	}
+	saidHello := make(chan saidHelloT)
+
+	tracing.Lock()
+	p := traceHello_Attach(nil, func(who string) {
+		saidHello <- saidHelloT{who, time.Now()}
+	})
+	tracing.Unlock()
+
+	go func() {
+		for hello := range saidHello {
+			fmt.Printf("Said hello to %v @ %v\n", hello.who, hello.when)
+		}
+	}()
+
+	SayHello("JP")
+	SayHello("Kirr")
+	SayHello("Varya")
+
+	tracing.Lock()
+	p.Detach()
+	tracing.Unlock()
+
+	close(saidHello)
+
+For convenience it is possible to keep group of attached probes and detach them
+all at once using ProbeGroup:
+
+	pg := &tracing.ProbeGroup{}
+
+	tracing.Lock()
+	traceHelloPre_Attach(pg, func(who string) { ... })
+	traceHello_Attach(pg, func(who string) { ... })
+	tracing.Unlock()
+
+	// some activity
+
+	// when probes needs to be detached (no explicit tracing.Lock needed):
+	pg.Done()
+
+Probes is general mechanism which allows various kind of usage of trace events.
+
+
+Cross package tracing
+
+Trace events are not part of exported package API with rationale that package's
+regular API and internal trace events usually have different stability
+commitments. However with tracing-specific importing mechanism it is possible
+to get access to trace events another package provides:
+
+	package another
+
+	//trace:import "hello"
+
+This will make _Attach functions for all tracing events from package hello be
+available as regular functions prefixed with imported package name:
+
+	tracing.Lock()
+	hello_traceHello_Attach(nil, func(who string) {
+		fmt.Printf("SayHello in package hello: %s", who)
+	tracing.Unlock()
+
+	...
+
+
+Gotrace
+
 TODO document `gotrace gen` + `gotrace list`
+
+--------
+
+(*) conditionally checking whether a pointer != nil. After
+https://golang.org/issues/19348 is implemented the call/return overhead will be
+also gone.
 */
 package tracing
 

go/xcommon/xio/xio.go

 // TODO copyright / license
 
-// Package xio provides addons to standard package io
+// Package xio provides addons to standard package io.
 package xio
 
 import (

go/xcommon/xnet/net.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package xnet provides addons to std package net
+// Package xnet provides addons to std package net.
 package xnet
 
 import (

go/xcommon/xnet/pipenet/pipenet.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package pipenet provides TCP-like synchronous in-memory network of net.Pipes
+// Package pipenet provides TCP-like synchronous in-memory network of net.Pipes.
 //
 // Addresses on pipenet are host:port pairs. A host is xnet.Networker and so
 // can be worked with similarly to regular TCP network with Dial/Listen/Accept/...

go/xcommon/xsync/xsync.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package xsync provides addons to packages "sync" and "golang.org/x/sync"
+// Package xsync provides addons to packages "sync" and "golang.org/x/sync".
 package xsync
 
 import (

go/xcommon/xtesting/xtesting.go

@@ -17,7 +17,7 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package xtesting provides addons to std package testing
+// Package xtesting provides addons to std package testing.
 package xtesting
 
 import (

go/zodb/wks/wks.go

@@ -17,7 +17,8 @@
 // See COPYING file for full licensing terms.
 // See https://www.nexedi.com/licensing for rationale and options.
 
-// Package wks links-in well-known ZODB storages
+// Package wks links-in well-known ZODB storages.
+//
 // The only purpose of this package is so that users could import it
 //
 //	import _ ".../zodb/wks"		XXX fixme import path