Skip to content

Commit

Permalink
all: update docs
Browse files Browse the repository at this point in the history
  • Loading branch information
changkun committed Feb 20, 2021
1 parent f558428 commit 19f27ae
Show file tree
Hide file tree
Showing 5 changed files with 115 additions and 31 deletions.
27 changes: 20 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,35 @@ import "golang.design/x/mainthread"

## API Usage

Package mainthread offers facilities to schedule functions on the
maint hread. To use this package properly, one must call
mainthread.Init from the main package. For example:

```go
package main

import "golang.design/x/mainthread"

func main() {
mainthread.Init(fn)
}
func main() { mainthread.Init(fn) }

// fn is the actual main function
func fn() {
mainthread.Call(func() {
// ... runs on the main thread ...
})
// mainthread.Call returns when f1 returns. Note that if f1 blocks
// it will also block the execution of any subsequent calls on the
// main thread.
mainthread.Call(f1)

// ... do whatever you want to do ...

// ... do what ever you want to do ...
// mainthread.Go returns immediately and f2 is scheduled to be executed
// in the future.
mainthread.Go(f2)

// ... do whatever you want to do ...
}

func f1() { ... }
func f2() { ... }
```

## When do you need this package?
Expand Down
24 changes: 24 additions & 0 deletions bench_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,24 @@
// Copyright 2020-2021 The golang.design Initiative Authors.
// All rights reserved. Use of this source code is governed
// by a MIT license that can be found in the LICENSE file.
//
// Written by Changkun Ou <changkun.de>

package mainthread_test

import (
"testing"

"golang.design/x/mainthread"
)

func BenchmarkCall(b *testing.B) {
f := func() {}
mainthread.Init(func() {
b.ReportAllocs()
b.ResetTimer()
for i := 0; i < b.N; i++ {
mainthread.Call(f)
}
})
}
40 changes: 40 additions & 0 deletions example_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
// Copyright 2020-2021 The golang.design Initiative Authors.
// All rights reserved. Use of this source code is governed
// by a MIT license that can be found in the LICENSE file.
//
// Written by Changkun Ou <changkun.de>

package mainthread_test

import (
"fmt"

"golang.design/x/mainthread"
)

func ExampleInit() {
mainthread.Init(func() {
// ... Do stuff ...
})
// Output:
}

func ExampleCall() {
mainthread.Init(func() {
mainthread.Call(func() {
fmt.Println("from main thread")
})
})
// Output: from main thread
}

func ExampleGo() {
mainthread.Init(func() {
done := make(chan string)
mainthread.Go(func() {
done <- "main thread"
})
fmt.Println("from", <-done)
})
// Output: from main thread
}
30 changes: 29 additions & 1 deletion mainthread.go
Original file line number Diff line number Diff line change
@@ -1,9 +1,37 @@
// Copyright 2021 The golang.design Initiative Authors.
// Copyright 2020-2021 The golang.design Initiative Authors.
// All rights reserved. Use of this source code is governed
// by a MIT license that can be found in the LICENSE file.
//
// Written by Changkun Ou <changkun.de>

// Package mainthread offers facilities to schedule functions on the
// maint hread. To use this package properly, one must call
// mainthread.Init from the main package. For example:
//
// package main
//
// import "golang.design/x/mainthread"
//
// func main() { mainthread.Init(fn) }
//
// // fn is the actual main function
// func fn() {
// // mainthread.Call returns when f1 returns. Note that if f1
// // blocks it will also block the execution of any subsequent
// // calls on the main thread.
// mainthread.Call(f1)
//
// // ... do whatever you want to do ...
//
// // mainthread.Go returns immediately and f2 is scheduled to be
// // executed in the future.
// mainthread.Go(f2)
//
// // ... do whatever you want to do ...
// }
//
// func f1() { ... }
// func f2() { ... }
package mainthread // import "golang.design/x/mainthread"

import (
Expand Down
25 changes: 2 additions & 23 deletions mainthread_test.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright 2021 The golang.design Initiative Authors.
// Copyright 2020-2021 The golang.design Initiative Authors.
// All rights reserved. Use of this source code is governed
// by a MIT license that can be found in the LICENSE file.
//
Expand All @@ -11,7 +11,6 @@ package mainthread_test

import (
"context"
"fmt"
"os"
"sync"
"sync/atomic"
Expand Down Expand Up @@ -85,31 +84,11 @@ func TestGo(t *testing.T) {
t.Fatalf("mainthread.Go is not executing in parallel")
}

ctxx, cancell := context.WithTimeout(context.Background(), time.Second)
ctxx, cancell := context.WithTimeout(context.Background(), time.Second*2)
defer cancell()
select {
case <-ctxx.Done():
t.Fatalf("mainthread.Go never schedules the function")
case <-done:
}
}

func BenchmarkCall(b *testing.B) {
f := func() {}
mainthread.Init(func() {
b.ReportAllocs()
b.ResetTimer()
for i := 0; i < b.N; i++ {
mainthread.Call(f)
}
})
}

func ExampleInit() {
mainthread.Init(func() {
mainthread.Call(func() {
fmt.Println("from main thread")
})
})
// Output: from main thread
}

0 comments on commit 19f27ae

Please sign in to comment.