| Index: third_party/go/src/golang.org/x/mobile/cmd/gobind/doc.go
|
| diff --git a/third_party/go/src/golang.org/x/mobile/cmd/gobind/doc.go b/third_party/go/src/golang.org/x/mobile/cmd/gobind/doc.go
|
| deleted file mode 100644
|
| index 12a567c2756f62238eeb9b21208dd59fe9f41e8a..0000000000000000000000000000000000000000
|
| --- a/third_party/go/src/golang.org/x/mobile/cmd/gobind/doc.go
|
| +++ /dev/null
|
| @@ -1,172 +0,0 @@
|
| -// Copyright 2014 The Go Authors. All rights reserved.
|
| -// Use of this source code is governed by a BSD-style
|
| -// license that can be found in the LICENSE file.
|
| -
|
| -/*
|
| -Gobind generates language bindings that make it possible to call Go code
|
| -and pass objects from Java.
|
| -
|
| -Using gobind
|
| -
|
| -Gobind takes a Go package and generates bindings for all of the exported
|
| -symbols. The exported symbols define the cross-language interface.
|
| -
|
| -The gobind tool generates both an API stub in Java, and binding code in
|
| -Go. Start with a Go package:
|
| -
|
| - package hi
|
| -
|
| - import "fmt"
|
| -
|
| - func Hello(name string) {
|
| - fmt.Println("Hello, %s!\n", name)
|
| - }
|
| -
|
| -Generate a Go binding package and Java stubs:
|
| -
|
| - go install golang.org/x/mobile/cmd/gobind
|
| - gobind -lang=go github.com/crawshaw/hi > hi/go_hi/go_hi.go
|
| - gobind -lang=java github.com/crawshaw/hi > hi/Hi.java
|
| -
|
| -The generated Go package, go_hi, must be linked into your Go program:
|
| -
|
| - import _ "github.com/crawshaw/hi/go_hi"
|
| -
|
| -Type restrictions
|
| -
|
| -At present, only a subset of Go types are supported.
|
| -
|
| -All exported symbols in the package must have types that are supported.
|
| -Supported types include:
|
| -
|
| - - Signed integer and floating point types.
|
| -
|
| - - String and boolean types.
|
| -
|
| - - Any function type all of whose parameters and results have
|
| - supported types. Functions must return either no results,
|
| - one result, or two results where the type of the second is
|
| - the built-in 'error' type.
|
| -
|
| - - Any interface type, all of whose exported methods have
|
| - supported function types.
|
| -
|
| - - Any struct type, all of whose exported methods have
|
| - supported function types and all of whose exported fields
|
| - have supported types.
|
| -
|
| -Unexported symbols have no effect on the cross-language interface, and
|
| -as such are not restricted.
|
| -
|
| -The set of supported types will eventually be expanded to cover all Go
|
| -types, but this is a work in progress.
|
| -
|
| -Exceptions and panics are not yet supported. If either pass a language
|
| -boundary, the program will exit.
|
| -
|
| -Passing Go objects to foreign languages
|
| -
|
| -Consider a type for counting:
|
| -
|
| - package mypkg
|
| -
|
| - type Counter struct {
|
| - Value int
|
| - }
|
| -
|
| - func (c *Counter) Inc() { c.Value++ }
|
| -
|
| - func New() *Counter { return &Counter{ 5 } }
|
| -
|
| -The generated bindings enable Java programs to create and use a Counter.
|
| -
|
| - public abstract class Mypkg {
|
| - private Mypkg() {}
|
| - public static final class Counter {
|
| - public void Inc() { ... }
|
| - public long GetValue() { ... }
|
| - public void SetValue(long value) { ... }
|
| - }
|
| - public static Counter New() { ... }
|
| - }
|
| -
|
| -The package-level function New can be called like so:
|
| -
|
| - Counter c = Mypkg.New()
|
| -
|
| -returns a Java Counter, which is a proxy for a Go *Counter. Calling the Inc
|
| -and Get methods will call the Go implementations of these methods.
|
| -
|
| -Passing foreign language objects to Go
|
| -
|
| -For a Go interface:
|
| -
|
| - package myfmt
|
| -
|
| - type Printer interface {
|
| - Print(s string)
|
| - }
|
| -
|
| - func PrintHello(p Printer) {
|
| - p.Print("Hello, World!")
|
| - }
|
| -
|
| -gobind generates a Java stub that can be used to implement a Printer:
|
| -
|
| - public abstract class Myfmt {
|
| - private Myfmt() {}
|
| - public interface Printer {
|
| - public void Print(String s);
|
| -
|
| - public static abstract class Stub implements Printer {
|
| - ...
|
| - }
|
| -
|
| - ...
|
| - }
|
| -
|
| - public static void PrintHello(Printer p) { ... }
|
| - }
|
| -
|
| -You can extend Myfmt.Printer.Stub to implement the Printer interface, and
|
| -pass it to Go using the PrintHello package function:
|
| -
|
| - public class SysPrint extends Myfmt.Printer.Stub {
|
| - public void Print(String s) {
|
| - System.out.println(s);
|
| - }
|
| - }
|
| -
|
| -The Java implementation can be used like so:
|
| -
|
| - Myfmt.Printer printer = new SysPrint();
|
| - Myfmt.PrintHello(printer);
|
| -
|
| -Avoid reference cycles
|
| -
|
| -The language bindings maintain a reference to each object that has been
|
| -proxied. When a proxy object becomes unreachable, its finalizer reports
|
| -this fact to the object's native side, so that the reference can be
|
| -removed, potentially allowing the object to be reclaimed by its native
|
| -garbage collector. The mechanism is symmetric.
|
| -
|
| -However, it is possible to create a reference cycle between Go and
|
| -Java objects, via proxies, meaning objects cannot be collected. This
|
| -causes a memory leak.
|
| -
|
| -For example, if a Go object G holds a reference to the Go proxy of a
|
| -Java object J, and J holds a reference to the Java proxy of G, then the
|
| -language bindings on each side must keep G and J live even if they are
|
| -otherwise unreachable.
|
| -
|
| -We recommend that implementations of foreign interfaces do not hold
|
| -references to proxies of objects. That is: if you extend a Stub in
|
| -Java, do not store an instance of Seq.Object inside it.
|
| -
|
| -Further reading
|
| -
|
| -Examples can be found in http://golang.org/x/mobile/example.
|
| -
|
| -Design doc: http://golang.org/s/gobind
|
| -*/
|
| -package main // import "golang.org/x/mobile/cmd/gobind"
|
|
|