PROTON-827: Merge branch 'master' into go1
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/4f6389ac Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/4f6389ac Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/4f6389ac Branch: refs/heads/go1 Commit: 4f6389aca34101e3f2cc24dbbf48e8aec293c379 Parents: ac6f824 e349a02 Author: Alan Conway <[email protected]> Authored: Fri May 22 15:38:18 2015 -0400 Committer: Alan Conway <[email protected]> Committed: Fri May 22 15:38:18 2015 -0400 ---------------------------------------------------------------------- .gitignore | 3 + .travis.yml | 2 +- LICENSE | 6 + README.md | 4 + appveyor.yml | 16 ++ go/README.md | 7 +- proton-c/bindings/python/MANIFEST.in | 2 + proton-c/bindings/python/proton/__init__.py | 7 +- proton-c/bindings/python/proton/reactor.py | 12 +- proton-c/bindings/python/setup.py | 188 ++++++++++++++++++- .../python/setuputils/PYZMQ_LICENSE.BSD | 32 ++++ proton-c/bindings/python/setuputils/__init__.py | 0 proton-c/bindings/python/setuputils/bundle.py | 84 +++++++++ proton-c/bindings/python/setuputils/log.py | 46 +++++ proton-c/bindings/python/setuputils/misc.py | 137 ++++++++++++++ proton-c/bindings/ruby/ruby.i | 14 ++ proton-c/include/proton/reactor.h | 2 + proton-c/include/proton/ssl.h | 8 + proton-c/src/reactor/acceptor.c | 15 ++ proton-c/src/ssl/openssl.c | 25 +++ proton-c/src/ssl/ssl_stub.c | 5 + proton-c/src/windows/schannel.c | 6 + 22 files changed, 608 insertions(+), 13 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/4f6389ac/go/README.md ---------------------------------------------------------------------- diff --cc go/README.md index 59ac624,0000000..4e72504 mode 100644,000000..100644 --- a/go/README.md +++ b/go/README.md @@@ -1,143 -1,0 +1,138 @@@ +# *EXPERIMENTAL* Go binding for proton + - NOTE: The go directory is in the proton repository root with a symlink at - proton-c/bindings/go to facilitate use of go tools: go get, godep and godoc. - There may be a cleaner solution to this in future. - +This is the beginning of a [Go](http://golang.org) binding for proton. + +This work is in early *experimental* stages, *everything* may change in future. +Comments and contributions are strongly encouraged, this experiment is public so +early feedback can guide development. + +- Email <[email protected]> +- Create issues <https://issues.apache.org/jira/browse/PROTON>, attach patches to an issue. + - There are working [examples](../examples/go/README.md) and the examples README file - explains how to install the packages in your go workspace and read the documentation. ++There are working [examples](../examples/go/README.md) + +## Goals + +The API should + +- be idiomatic, unsurprising, and easy to use for Go developers. +- support client and server development. +- make simple tasks simple. +- provide deep access to AMQP protocol when that is required. + +There are two types of developer we want to support + +1. Go developers using AMQP as a message transport: + - Straightforward conversions between Go built-in types and AMQP types. + - Easy message exchange via Go channels to support use in goroutines. + +2. AMQP-aware developers using Go as an implementation language: + - Go types to exactly represent all AMQP types and encoding details. + - Full access to detailed AMQP concepts: sessions, links, deliveries etc. + +## Status + +There are 3 go packages for proton: + +- qpid.apache.org/proton/go/amqp: converts AMQP messages and data types to and from Go data types. +- qpid.apache.org/proton/go/messaging: easy-to-use, concurrent API for messaging clients and servers. +- qpid.apache.org/proton/go/event: full low-level access to the proton engine. + +Most applications should use the `messaging` package. The `event` package is for +applications that need low-level access to the proton engine. + +The `event` package is fairly complete, with the exception of the proton +reactor. It's unclear if the reactor is important for go. + +The `messaging` package can run the examples but probably not much else. There +is work to do on error handling and the API may change. + +There are working [examples](../../../examples/go/README.md) of a broker using `event` and +a sender and receiver using `messaging`. + +## The event driven API + +See the package documentation for details. + +## The Go API + +The goal: A procedural API that allows any user goroutine to send and receive +AMQP messages and other information (acknowledgments, flow control instructions +etc.) using channels. There will be no user-visible locks and no need to run +user code in special goroutines, e.g. as handlers in a proton event loop. + +See the package documentation for emerging details. + +Currently using a channel to receive messages, a function to send them (channels +internally) and a channel as a "future" for acknowledgements to senders. This +may change. + +## Why a separate API for Go? + +Go is a concurrent language and encourages applications to be divided into +concurrent *goroutines*. It provides traditional locking but it encourages the +use *channels* to communicate between goroutines without explicit locks: + + "Share memory by communicating, don't communicate by sharing memory" + +The idea is that a given value is only operated on by one goroutine at a time, +but values can easily be passed from one goroutine to another. This removes much +of the need for locking. + +Go literature distinguishes between: + +- *concurrency*: "keeping track of things that could be done in parallel" +- *parallelism*: "actually doing things in parallel" + +The application expresses concurrency by starting goroutines for potentially +concurrent tasks. The Go run-times schedule the activity of goroutines onto a +small number (possibly one) of actual parallel executions. + +Even with *no* parallelism, concurrency lets the Go run-times *order* work with +respect to events like file descriptors being readable/writable, channels having +data, timers firing etc. Go automatically takes care of switching out goroutines +that block or sleep so it is normal to write code in terms of blocking calls. + +Event-driven API (like poll, epoll, select or the proton event API) also +channel unpredictably ordered events to actions in one or a small pool of +execution threads. However this requires a different style of programming: +"event-driven" or "reactive" programming. Go developers call it "inside-out" +programming. In an event-driven architecture blocking is a big problem as it +consumes a scarce thread of execution, so actions that take time to complete +have to be re-structured in terms of future event delivery. + +The promise of Go is that you can express your application in concurrent, +procedural terms with simple blocking calls and the Go run-times will turn it +inside-out for you. Write as many goroutines as you want, and let Go interleave +and schedule them efficiently. + +For example: the Go equivalent of listening for connections is a goroutine with +a simple endless loop that calls a blocking Listen() function and starts a +goroutine for each new connection. Each connection has its own goroutine that +deals with just that connection till it closes. + +The benefit is that the variables and logic live closer together. Once you're in +a goroutine, you have everything you need in local variables, and they are +preserved across blocking calls. There's no need to store details in context +objects that you have to look up when handling a later event to figure out how +to continue where you left off. + +So a Go-like proton API does not force the users code to run in an event-loop +goroutine. Instead user goroutines communicate with the event loop(s) via +channels. There's no need to funnel connections into one event loop, in fact it +makes no sense. Connections can be processed concurrently so they should be +processed in separate goroutines and left to Go to schedule. User goroutines can +have simple loops that block channels till messages are available, the user can +start as many or as few such goroutines as they wish to implement concurrency as +simple or as complex as they wish. For example blocking request-response +vs. asynchronous flows of messages and acknowledgments. + +## New to Go? + +If you are new to Go then these are a good place to start: + +- [A Tour of Go](http://tour.golang.org) +- [Effective Go](http://golang.org/doc/effective_go.html) + +Then look at the tools and library docs at <http://golang.org> as you need them. + --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
