Merge pull request #52 from MicahParks/master

Document main thread conversion requirement in more places

README.md

@@ -43,6 +43,10 @@ Full documentation can be found at https://pkg.go.dev/github.com/adrg/go-wkhtmlt
 * [Basic web page to PDF conversion server](examples/http-server)
 * [Configurable web page to PDF conversion server](examples/http-server-advanced)
 
+> Note: The `HTML` to `PDF` conversion (calls to the `Converter.Run` method) must be performed on the main thread.
+> This is a limitation of the wkhtmltox library. Please see the basic `HTTP` server [example](examples/http-server)
+> for more information.
+
 ## Prerequisites
 
 In order to use the package, `wkhtmltox` must be installed. Installation packages
@@ -129,14 +133,15 @@ func main() {
 	converter.MarginLeft = "10mm"
 	converter.MarginRight = "10mm"
 
-	// Convert objects and save the output PDF document.
+	// Create output file.
 	outFile, err := os.Create("out.pdf")
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer outFile.Close()
 
-	// Run converter.
+	// Run converter. Due to a limitation of the `wkhtmltox` library, the
+	// conversion must be performed on the main thread.
 	if err := converter.Run(outFile); err != nil {
 		log.Fatal(err)
 	}

converter.go

@@ -284,6 +284,8 @@ func (c *Converter) Add(object *Object) {
 }
 
 // Run performs the conversion and copies the output to the provided writer.
+// Due to a limitation of the `wkhtmltox` library, this method must be called
+// on the main thread.
 func (c *Converter) Run(w io.Writer) error {
 	if c.converter == nil {
 		return errors.New("cannot use uninitialized or destroyed converter")

examples/basic-usage/main.go

@@ -67,14 +67,15 @@ func main() {
 	converter.MarginLeft = "10mm"
 	converter.MarginRight = "10mm"
 
-	// Convert objects and save the output PDF document.
+	// Create output file.
 	outFile, err := os.Create("out.pdf")
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer outFile.Close()
 
-	// Run converter.
+	// Run converter. Due to a limitation of the `wkhtmltox` library, the
+	// conversion must be performed on the main thread.
 	if err := converter.Run(outFile); err != nil {
 		log.Fatal(err)
 	}

examples/converter-callbacks/main.go

@@ -52,13 +52,15 @@ func main() {
 
 	converter.Add(object)
 
-	// Convert objects and save the output PDF document.
+	// Create output file.
 	outFile, err := os.Create("out.pdf")
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer outFile.Close()
 
+	// Run converter. Due to a limitation of the `wkhtmltox` library, the
+	// conversion must be performed on the main thread.
 	if err := converter.Run(outFile); err != nil {
 		log.Fatal(err)
 	}

examples/http-server-advanced/main.go

@@ -97,7 +97,8 @@ func startServer() {
 			// Add object to the converter.
 			converter.Add(object)
 
-			// Perform the conversion.
+			// Run converter. Due to a limitation of the `wkhtmltox` library,
+			// the conversion must be performed on the main thread.
 			return converter.Run(out)
 		}); err != nil {
 			http.Error(w, err.Error(), http.StatusInternalServerError)

examples/http-server/main.go

@@ -88,7 +88,8 @@ func startServer() {
 			converter.Title = url
 			converter.PaperSize = pdf.A4
 
-			// Perform the conversion.
+			// Run converter. Due to a limitation of the `wkhtmltox` library,
+			// the conversion must be performed on the main thread.
 			return converter.Run(out)
 		}); err != nil {
 			http.Error(w, err.Error(), http.StatusInternalServerError)

examples/json-input/main.go

@@ -67,13 +67,15 @@ func main() {
 	// Add object to the converter.
 	converter.Add(object)
 
-	// Convert object and save the output PDF document.
+	// Create output file.
 	outFile, err := os.Create("out.pdf")
 	if err != nil {
 		log.Fatal(err)
 	}
 	defer outFile.Close()
 
+	// Run converter. Due to a limitation of the `wkhtmltox` library, the
+	// conversion must be performed on the main thread.
 	if err := converter.Run(outFile); err != nil {
 		log.Fatal(err)
 	}

pdf.go

@@ -3,6 +3,7 @@ Package pdf implements wkhtmltopdf Go bindings. It can be used to convert HTML d
 The package does not use the wkhtmltopdf binary. Instead, it uses the wkhtmltox library directly.
 
 Example
+
 	package main
 
 	import (
@@ -69,13 +70,15 @@ Example
 		converter.MarginLeft = "10mm"
 		converter.MarginRight = "10mm"
 
-		// Convert objects and save the output PDF document.
+		// Create output file.
 		outFile, err := os.Create("out.pdf")
 		if err != nil {
 			log.Fatal(err)
 		}
 		defer outFile.Close()
 
+		// Run converter. Due to a limitation of the `wkhtmltox` library, the
+		// conversion must be performed on the main thread.
 		if err := converter.Run(outFile); err != nil {
 			log.Fatal(err)
 		}