From 3600c8aa6c8a91c81b1f1ba2afc665f1e32b6c33 Mon Sep 17 00:00:00 2001
From: Hajime Hoshi <hajimehoshi@gmail.com>
Date: Wed, 10 Oct 2018 23:23:28 +0900
Subject: [PATCH] ui: Add documents about concurrent-safety

Fixes #709.
---
 doc.go | 4 ++++
 run.go | 8 ++++----
 2 files changed, 8 insertions(+), 4 deletions(-)

diff --git a/doc.go b/doc.go
index 038e535d7..2317b6d88 100644
--- a/doc.go
+++ b/doc.go
@@ -45,4 +45,8 @@
 // The EBITEN_INTERNAL_IMAGES_KEY environment variable specifies the key
 // to dump all the internal images. This is valid only when the build tag
 // 'ebitendebug' is specified.
+//
+// In the API document, 'the main thread' means the goroutine in init(), main() and their callees without 'go'
+// statement. It is assured that 'the main thread' runs on the OS main thread. There are some Ebiten functions that
+// must be called on the main thread under some conditions (typically, before ebiten.Run is called).
 package ebiten
diff --git a/run.go b/run.go
index 2d711092d..fd716066f 100644
--- a/run.go
+++ b/run.go
@@ -254,7 +254,7 @@ func (i *imageDumper) update(screen *Image) error {
 // you can disable this automatical device scaling as a result.
 // You can get the device scale by DeviceScaleFactor function.
 //
-// Run must be called from the OS main thread.
+// Run must be called on the main thread.
 // Note that Ebiten bounds the main goroutine to the main OS thread by runtime.LockOSThread.
 //
 // Ebiten tries to call f 60 times a second. In other words,
@@ -342,7 +342,7 @@ func RunWithoutMainLoop(f func(*Image) error, width, height int, scale float64,
 //
 // For actual example, see examples/fullscreen
 //
-// ScreenSizeInFullscreen is concurrent-safe.
+// ScreenSizeInFullscreen must be called on the main thread before ebiten.Run, and is concurrent-safe after ebiten.Run.
 func ScreenSizeInFullscreen() (int, int) {
 	return ui.ScreenSizeInFullscreen()
 }
@@ -524,7 +524,7 @@ func SetWindowIcon(iconImages []image.Image) {
 // DeviceScaleFactor might panic on init function on some devices like Android.
 // Then, it is not recommended to call DeviceScaleFactor from init functions.
 //
-// DeviceScaleFactor is concurrent-safe.
+// DeviceScaleFactor must be called on the main thread before ebiten.Run, and is concurrent-safe after ebiten.Run.
 func DeviceScaleFactor() float64 {
 	return ui.DeviceScaleFactor()
 }
@@ -565,7 +565,7 @@ func MaxTPS() int {
 // CurrentTPS returns the current TPS (ticks per second),
 // that represents how many update function is called in a second.
 //
-// CurrentTPS is concurrent safe.
+// CurrentTPS is concurrent-safe.
 func CurrentTPS() float64 {
 	return clock.CurrentTPS()
 }