NO-JIRA: go: merge doc updates from master 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/793e2101 Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/793e2101 Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/793e2101 Branch: refs/heads/go1 Commit: 793e210100d0d75d32660eedd9f553a32d6f1f78 Parents: 4afe30d 951dcb4 Author: Alan Conway <[email protected]> Authored: Mon Jan 9 10:22:28 2017 -0500 Committer: Alan Conway <[email protected]> Committed: Mon Jan 9 10:22:28 2017 -0500 ---------------------------------------------------------------------- README.md | 5 +++++ amqp/doc.go | 2 ++ electron/doc.go | 2 ++ proton/doc.go | 2 ++ 4 files changed, 11 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/793e2101/README.md ---------------------------------------------------------------------- diff --cc README.md index ffd67f8,44e1fdd..7415929 --- a/README.md +++ b/README.md @@@ -1,97 -1,43 +1,102 @@@ -Qpid Proton - AMQP messaging toolkit -==================================== +# Qpid Go packages for AMQP -Linux Build | Windows Build -------------|-------------- -[](https://travis-ci.org/apache/qpid-proton) | [](https://ci.appveyor.com/project/ke4qqq/qpid-proton/branch/master) +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> -Qpid Proton is a high-performance, lightweight messaging library. It can be -used in the widest range of messaging applications, including brokers, client -libraries, routers, bridges, proxies, and more. Proton makes it trivial to -integrate with the AMQP 1.0 ecosystem from any platform, environment, or -language ++They require the [proton-C library](http://qpid.apache.org/proton) to be installed. ++On many platforms it is avaialable pre-packaged, for example on Fedora + -Features --------- ++ yum install qpid-proton-c-devel + - + A flexible and capable reactive messaging API - + Full control of AMQP 1.0 protocol semantics - + Portable C implementation with bindings to popular languages - + Peer-to-peer and brokered messaging - + Secure communication via SSL and SASL +There are 3 packages: -Universal - Proton is designed to scale both up and down. Equally suitable for -simple clients or high-powered servers, it can be deployed in simple -peer-to-peer configurations or as part of a global federated messaging network. +[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. -Embeddable - Proton is carefully written to be portable and cross platform. It -has minimal dependencies, and it is architected to be usable with any threading -model, as well as with non-threaded applications. These features make it -uniquely suited for embedding messaging capabilities into existing software. +[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. -Standard - Built around the AMQP 1.0 messaging standard, Proton is not only -ideal for building out your own messaging applications but also for connecting -them to the broader ecosystem of AMQP 1.0-based messaging applications. +[qpid.apache.org/proton](http://godoc.org/qpid.apache.org/proton) is an +event-driven, concurrent-unsafe package that closely follows the proton C +API. Most Go programmers will find the +[electron](http://godoc.org/qpid.apache.org/electron) package easier to use. -Getting Started ---------------- +See the [examples](https://github.com/apache/qpid-proton/blob/master/examples/go/README.md) +to help you get started. -See the included INSTALL file for build and install instructions and the -DEVELOPERS file for information on how to modify and test the library code -itself. +Feedback is encouraged at: -Please see http://qpid.apache.org/proton for a more info. +- Email <[email protected]> +- Create issues <https://issues.apache.org/jira/browse/PROTON>, attach patches to an issue. + +### Why two APIs? + +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 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 on multiple CPUs or cores" + +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 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? + +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 docs at <http://golang.org> as you need them. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/793e2101/amqp/doc.go ---------------------------------------------------------------------- diff --cc amqp/doc.go index 97051a5,0000000..701af55 mode 100644,000000..100644 --- a/amqp/doc.go +++ b/amqp/doc.go @@@ -1,36 -1,0 +1,38 @@@ +/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/ + +/* +Package amqp encodes and decodes AMQP 1.0 messages and data types as Go types. + +It follows the standard 'encoding' libraries pattern. The mapping between AMQP +and Go types is described in the documentation of the Marshal and Unmarshal +functions. + ++This package requires the [proton-C library](http://qpid.apache.org/proton) to be installed. ++ +Package 'electron' is a full AMQP 1.0 client/server toolkit using this package. + +AMQP 1.0 is an open standard for inter-operable message exchange, see <http://www.amqp.org/> +*/ +package amqp + +// #cgo LDFLAGS: -lqpid-proton +import "C" + +// This file is just for the package comment. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/793e2101/electron/doc.go ---------------------------------------------------------------------- diff --cc electron/doc.go index bc2c589,0000000..f4baa31 mode 100644,000000..100644 --- a/electron/doc.go +++ b/electron/doc.go @@@ -1,71 -1,0 +1,73 @@@ +/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/ + +/* +Package electron lets you write concurrent AMQP 1.0 messaging clients and servers. + ++This package requires the [proton-C library](http://qpid.apache.org/proton) to be installed. ++ +Start by creating a Container with NewContainer. An AMQP Container represents a +single AMQP "application" and can contain client and server connections. + +You can enable AMQP over any connection that implements the standard net.Conn +interface. Typically you can connect with net.Dial() or listen for server +connections with net.Listen. Enable AMQP by passing the net.Conn to +Container.Connection(). + +AMQP allows bi-direction peer-to-peer message exchange as well as +client-to-broker. Messages are sent over "links". Each link is one-way and has a +Sender and Receiver end. Connection.Sender() and Connection.Receiver() open +links to Send() and Receive() messages. Connection.Incoming() lets you accept +incoming links opened by the remote peer. You can open and accept multiple links +in both directions on a single Connection. + +Some of the documentation examples show client and server side by side in a +single program, in separate goroutines. This is only for example purposes, real +AMQP applications would run in separate processes on the network. +More realistic examples: https://github.com/apache/qpid-proton/blob/master/examples/go/README.md + +Some of the documentation examples show client and server side by side in a +single program, in separate goroutines. This is only for example purposes, real +AMQP applications would run in separate processes on the network. +More realistic examples: https://github.com/apache/qpid-proton/blob/master/examples/go/README.md + +*/ +package electron + +//#cgo LDFLAGS: -lqpid-proton +import "C" + +// Just for package comment + +/* DEVELOPER NOTES + +There is a single proton.Engine per connection, each driving it's own event-loop goroutine, +and each with a 'handler'. Most state for a connection is maintained on the handler, and +only accessed in the event-loop goroutine, so no locks are required there. + +The handler sets up channels as needed to get or send data from user goroutines +using electron types like Sender or Receiver. + +Engine.Inject injects actions into the event loop from user goroutines. It is +important to check at the start of an injected function that required objects +are still valid, for example a link may be remotely closed between the time a +Sender function calls Inject and the time the injected function is execute by +the handler goroutine. + +*/ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/793e2101/proton/doc.go ---------------------------------------------------------------------- diff --cc proton/doc.go index 083f701,0000000..1049e71 mode 100644,000000..100644 --- a/proton/doc.go +++ b/proton/doc.go @@@ -1,64 -1,0 +1,66 @@@ +/* +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +*/ + +/* +Package proton wraps Proton-C, an event-driven, concurrent-unsafe AMQP 1.0 +C library (package 'electron' is more "Go-like" and concurrent-safe) + ++This package requires the [proton-C library](http://qpid.apache.org/proton) to be installed. ++ +Consult the C API documentation at http://qpid.apache.org/proton for more +information about the types here. There is a 1-1 correspondence between C type +pn_foo_t and Go type proton.Foo, and between C function + + pn_foo_do_something(pn_foo_t*, ...) + +and Go method + + func (proton.Foo) DoSomething(...) + +The proton.Engine type pumps data between a Go net.Conn and a proton event loop +goroutine that feeds events to a proton.MessagingHandler, which you must implement. +See the Engine documentation for more. + +MessagingHandler defines an event handling interface that you can implement to +react to AMQP protocol events. There is also a lower-level EventHandler, but +MessagingHandler provides a simpler set of events and automates common tasks for you, +for most applications it will be more convenient. + +NOTE: Methods on most types defined in this package (Sessions, Links etc.) can +*only* be called in the event handler goroutine of the relevant +Connection/Engine, either by the HandleEvent method of a handler type or in a +function injected into the goroutine via Inject() or InjectWait() Handlers and +injected functions can set up channels to communicate with other goroutines. +Note the Injecter associated with a handler available as part of the Event value +passed to HandleEvent. + +Separate Engine instances are independent, and can run concurrently. + +The 'electron' package is built on the proton package but instead offers a +concurrent-safe API that can use simple procedural loops rather than event +handlers to express application logic. It is easier to use for most +applications. + +*/ +package proton + +// #cgo LDFLAGS: -lqpid-proton +import "C" + +// This file is just for the package comment. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
