fix(measurex): allow API user to choose parallelism (#581)

Closes https://github.com/ooni/probe/issues/1818

internal/tutorial/measurex/chapter09/README.md

@@ -87,9 +87,14 @@ Then, we call `HTTPEndpointGetParallel`. The arguments are:
 
 - all the endpoints to measure
 
+The parallelism argument tells the code how many parallel goroutines
+to use for parallelizable operations. If this value is zero or negative,
+the code will use a reasonably small default.
+
 ```Go
 	cookies := measurex.NewCookieJar()
-	for epnt := range mx.HTTPEndpointGetParallel(ctx, cookies, httpEndpoints...) {
+	const parallelism = 3
+	for epnt := range mx.HTTPEndpointGetParallel(ctx, parallelism, cookies, httpEndpoints...) {
 		m.Endpoints = append(m.Endpoints, epnt)
 	}
 ```

internal/tutorial/measurex/chapter09/main.go

@@ -88,9 +88,14 @@ func main() {
 	//
 	// - all the endpoints to measure
 	//
+	// The parallelism argument tells the code how many parallel goroutines
+	// to use for parallelizable operations. If this value is zero or negative,
+	// the code will use a reasonably small default.
+	//
 	// ```Go
 	cookies := measurex.NewCookieJar()
-	for epnt := range mx.HTTPEndpointGetParallel(ctx, cookies, httpEndpoints...) {
+	const parallelism = 3
+	for epnt := range mx.HTTPEndpointGetParallel(ctx, parallelism, cookies, httpEndpoints...) {
 		m.Endpoints = append(m.Endpoints, epnt)
 	}
 	// ```

internal/tutorial/measurex/chapter10/README.md

@@ -90,7 +90,8 @@ scheme is "https". Otherwise, if it's just "http", it
 does not make sense to send this query.
 
 ```Go
-	for dns := range mx.LookupURLHostParallel(ctx, parsed, resolvers...) {
+	const parallelism = 3
+	for dns := range mx.LookupURLHostParallel(ctx, parallelism, parsed, resolvers...) {
 		m.DNS = append(m.DNS, dns)
 	}
 ```
@@ -102,7 +103,7 @@ The rest of the program is exactly like in chapter09.
 	httpEndpoints, err := measurex.AllHTTPEndpointsForURL(parsed, headers, m.DNS...)
 	runtimex.PanicOnError(err, "cannot get all the HTTP endpoints")
 	cookies := measurex.NewCookieJar()
-	for epnt := range mx.HTTPEndpointGetParallel(ctx, cookies, httpEndpoints...) {
+	for epnt := range mx.HTTPEndpointGetParallel(ctx, parallelism, cookies, httpEndpoints...) {
 		m.Endpoints = append(m.Endpoints, epnt)
 	}
 	print(m)

internal/tutorial/measurex/chapter10/main.go

@@ -91,7 +91,8 @@ func main() {
 	// does not make sense to send this query.
 	//
 	// ```Go
-	for dns := range mx.LookupURLHostParallel(ctx, parsed, resolvers...) {
+	const parallelism = 3
+	for dns := range mx.LookupURLHostParallel(ctx, parallelism, parsed, resolvers...) {
 		m.DNS = append(m.DNS, dns)
 	}
 	// ```
@@ -103,7 +104,7 @@ func main() {
 	httpEndpoints, err := measurex.AllHTTPEndpointsForURL(parsed, headers, m.DNS...)
 	runtimex.PanicOnError(err, "cannot get all the HTTP endpoints")
 	cookies := measurex.NewCookieJar()
-	for epnt := range mx.HTTPEndpointGetParallel(ctx, cookies, httpEndpoints...) {
+	for epnt := range mx.HTTPEndpointGetParallel(ctx, parallelism, cookies, httpEndpoints...) {
 		m.Endpoints = append(m.Endpoints, epnt)
 	}
 	print(m)

internal/tutorial/measurex/chapter11/README.md

@@ -65,6 +65,10 @@ The arguments are:
 
 - the context as usual
 
+- the number of parallel goroutines to use to perform parallelizable
+operations (passing zero or negative will cause the code to use
+a reasonably small default value)
+
 - the unparsed URL to measure
 
 - the headers we want to use
@@ -72,7 +76,8 @@ The arguments are:
 - a jar for cookies
 
 ```Go
-	m, err := mx.MeasureURL(ctx, *URL, headers, cookies)
+	const parallelism = 3
+	m, err := mx.MeasureURL(ctx, parallelism, *URL, headers, cookies)
 ```
 The return value is either an `URLMeasurement`
 or an error. The error happens, for example, if

internal/tutorial/measurex/chapter11/main.go

@@ -66,6 +66,10 @@ func main() {
 	//
 	// - the context as usual
 	//
+	// - the number of parallel goroutines to use to perform parallelizable
+	// operations (passing zero or negative will cause the code to use
+	// a reasonably small default value)
+	//
 	// - the unparsed URL to measure
 	//
 	// - the headers we want to use
@@ -73,7 +77,8 @@ func main() {
 	// - a jar for cookies
 	//
 	// ```Go
-	m, err := mx.MeasureURL(ctx, *URL, headers, cookies)
+	const parallelism = 3
+	m, err := mx.MeasureURL(ctx, parallelism, *URL, headers, cookies)
 	// ```
 	// The return value is either an `URLMeasurement`
 	// or an error. The error happens, for example, if

internal/tutorial/measurex/chapter12/README.md

@@ -62,11 +62,16 @@ returns a channel where it posts the result of measuring
 the original URL along with all its redirections. Internally,
 `MeasureURLAndFollowRedirections` calls `MeasureURL`.
 
+The parallelism argument dictates how many parallel goroutine
+to use for parallelizable operations. (A zero or negative
+value implies that the code should use a sensible default value.)
+
 We accumulate the results in `URLs` and print `m`. The channel
 is closed when done by `MeasureURLAndFollowRedirections`, so we leave the loop.
 
 ```Go
-	for m := range mx.MeasureURLAndFollowRedirections(ctx, *URL, headers, cookies) {
+	const parallelism = 3
+	for m := range mx.MeasureURLAndFollowRedirections(ctx, parallelism, *URL, headers, cookies) {
 		all.URLs = append(all.URLs, measurex.NewArchivalURLMeasurement(m))
 	}
 	print(all)

internal/tutorial/measurex/chapter12/main.go

@@ -63,11 +63,16 @@ func main() {
 	// the original URL along with all its redirections. Internally,
 	// `MeasureURLAndFollowRedirections` calls `MeasureURL`.
 	//
+	// The parallelism argument dictates how many parallel goroutine
+	// to use for parallelizable operations. (A zero or negative
+	// value implies that the code should use a sensible default value.)
+	//
 	// We accumulate the results in `URLs` and print `m`. The channel
 	// is closed when done by `MeasureURLAndFollowRedirections`, so we leave the loop.
 	//
 	// ```Go
-	for m := range mx.MeasureURLAndFollowRedirections(ctx, *URL, headers, cookies) {
+	const parallelism = 3
+	for m := range mx.MeasureURLAndFollowRedirections(ctx, parallelism, *URL, headers, cookies) {
 		all.URLs = append(all.URLs, measurex.NewArchivalURLMeasurement(m))
 	}
 	print(all)