[32/50] [abbrv] qpid-proton git commit: NO-JIRA: Correct go documentation links.

[ac...@apache.org]

NO-JIRA: Correct go documentation links.


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/dc5cbac0
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/dc5cbac0
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/dc5cbac0

Branch: refs/heads/go1
Commit: dc5cbac0a8f9e77cf91a6def28d0fcfbe4d4dfa8
Parents: abea588
Author: Alan Conway <ac...@redhat.com>
Authored: Mon Oct 19 14:08:29 2015 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Mon Oct 19 15:01:50 2015 -0400

----------------------------------------------------------------------
 .../bindings/go/src/qpid.apache.org/README.md   | 147 +++++++++----------
 1 file changed, 69 insertions(+), 78 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/dc5cbac0/proton-c/bindings/go/src/qpid.apache.org/README.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/qpid.apache.org/README.md b/proton-c/bindings/go/src/qpid.apache.org/README.md
index b99047d..21dcc19 100644
--- a/proton-c/bindings/go/src/qpid.apache.org/README.md
+++ b/proton-c/bindings/go/src/qpid.apache.org/README.md
@@ -1,99 +1,90 @@
 # Qpid Go Libraries for AMQP
 
-These packages provide [Go](http://golang.org) support for sending and receiving AMQP
-messages in client or server applications.
+These packages provide [Go](http://golang.org) support for sending and receiving
+AMQP messages in client or server applications. Reference documentation is
+available at: <http://godoc.org/?q=qpid.apache.org>
 
-Package documentation is available at: <http://godoc.org/qpid.apache.org/>
+There are 3 packages:
 
-See the [examples](https://github.com/apache/qpid-proton/blob/master/examples/go/README.md)
-for working examples and practical instructions on how to get started.
+[qpid.apache.org/amqp](http://godoc.org/qpid.apache.org/amqp) provides functions
+to convert AMQP messages and data types to and from Go data types.  Used by both
+the proton and electron packages to manage AMQP data.
 
-Feedback is encouraged at:
-
-- Email <pr...@qpid.apache.org>
-- Create issues <https://issues.apache.org/jira/browse/PROTON>, attach patches to an issue.
-
-## Status
-
-There are 3 go packages for proton:
+[qpid.apache.org/electron](http://godoc.org/qpid.apache.org/electron) is a
+simple, concurrent-safe API for sending and receiving messages. It can be used
+with goroutines and channels to build concurrent AMQP clients and servers.
 
-`qpid.apache.org/electron`:  procedural, concurrent-safe Go library for AMQP messaging.
-A simple procedural API that can easily be used with goroutines and channels to construct
-concurrent AMQP clients and servers.
+[qpid.apache.org/proton](http://godoc.org/qpid.apache.org/proton) is an
+event-driven, concurrent-unsafe library that closely follows the proton C
+API. Most Go programmers will find the electron library easier to use.
 
-`qpid.apache.org/proton`: event-driven, concurrent-unsafe Go library for AMQP messaging.
-A simple port into Go of the Proton C library. Its event-driven, single-threaded nature
-may be off-putting for Go programmers, hence the electron API.
+There are [examples](https://github.com/apache/qpid-proton/blob/master/examples/go/README.md)
+to help you get started.
 
-`qpid.apache.org/amqp`: converts AMQP messages and data types to and from Go data types.
-Used by both the proton and electron packages to represent AMQP types.
-
-See the
-[examples](https://github.com/apache/qpid-proton/blob/master/examples/go/README.md)
-for an illustration of the APIs, in particular compare `proton/broker.go` and
-`electron/broker.go` which illustrate the different API approaches to the same
-task (a simple broker.)
+Feedback is encouraged at:
 
+- Email <pr...@qpid.apache.org>
+- Create issues <https://issues.apache.org/jira/browse/PROTON>, attach patches to an issue.
 
 ### Why two APIs?
 
-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.
+The `proton` API is a direct mapping of the proton C library into Go. It is
+usable but not very natural for a Go programmer because it takes an
+*event-driven* approach and has no built-in support for concurrent
+use. `electron` uses `proton` internally but provides a more Go-like API that is
+safe to use from multiple concurrent goroutines.
 
-Go literature distinguishes between:
+Go encourages programs to be structured as concurrent *goroutines* that
+communicate via *channels*. Go literature distinguishes between:
 
 - *concurrency*: "keeping track of things that could be done in parallel"
-- *parallelism*: "actually doing things in parallel"
+- *parallelism*: "actually doing things in parallel on multiple CPUs or cores"
 
-The application expresses concurrency by starting goroutines for potentially
-concurrent tasks. The Go run-times schedule the activity of goroutines onto a
+A Go program expresses concurrency by starting goroutines for potentially
+concurrent tasks. The Go runtime schedules 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 programming (such as poll, epoll, select or the `proton` package)
-also channels 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.
-
-The `proton` API is important because it is close to the original proton-C
-reactive API and gives you direct access to the underlying library. However it
-is un-Go-like in it's event-driven nature, and it requires care as methods on
-values associated with the same underlying proton engine are not
-concurrent-safe.
-
-The `electron` API hides the event-driven details behind a simple blocking API
-that can be safely called from arbitrary goroutines. Under the covers data is
-passed through channels to dedicated goroutines running separate `proton` event
-loops for each connection.
+Even with no hardware parallelism, goroutine concurrency lets the Go runtime
+order unpredictable 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.
+
+By contrast, event-driven programming is based on polling mechanisms like
+`select`, `poll` or `epoll`. These also dispatch unpredictably ordered events to
+a single thread or a small thread pool. However this requires a different style
+of programming: "event-driven" or "reactive" programming. Go developers call it
+"inside-out" programming.  In an event-driven program 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 multiple events.
+
+The promise of Go is that you can express your program in concurrent, sequential
+terms and the Go runtime will turn it inside-out for you. You can start
+goroutines for all concurrent activities. They can loop forever or block for as
+long as they need waiting for timers, IO or any unpredictable event. Go will
+interleave and schedule them efficiently onto the available parallel hardware.
+
+For example: in the `electron` API, you can send a message and wait for it to be
+acknowledged in a single function. All the information about the message, why
+you sent it, and what to do when it is acknowledged can be held in local
+variables, all the code is in a simple sequence. Other goroutines in your
+program can be sending and receiving messages concurrently, they are not
+blocked.
+
+In the `proton` API, an event handler that sends a message must return
+*immediately*, it cannot block the event loop to wait for
+acknowledgement. Acknowledgement is a separate event, so the code for handling
+it is in a different event handler. Context information about the message has to
+be stored in some non-local variable that both functions can find. This makes
+the code harder to follow.
+
+The `proton` API is important because it is the foundation for the `electron`
+API, and may be useful for programs that need to be close to the original C
+library for some reason. However the `electron` API hides the event-driven
+details behind simple, sequential, concurrent-safe methods that can be called
+from arbitrary goroutines. Under the covers, data is passed through channels to
+dedicated `proton` goroutines so user goroutines can work concurrently with the
+proton event-loop.
 
 ## New to Go?
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org