qpid-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From acon...@apache.org
Subject [24/24] qpid-proton git commit: PROTON-827: Merge branch 'master' into go1
Date Fri, 22 May 2015 19:45:47 GMT
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 <aconway@redhat.com>
Authored: Fri May 22 15:38:18 2015 -0400
Committer: Alan Conway <aconway@redhat.com>
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(-)

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 <proton@qpid.apache.org>
 +- 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
 +- 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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org

View raw message