You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2016/11/02 03:19:17 UTC
[1/2] qpid-proton git commit: PROTON-1338: Go: update package
documentation.
Repository: qpid-proton
Updated Branches:
refs/heads/go1 287eeacaf -> f405d29a5
PROTON-1338: Go: update package documentation.
Clarify AMQP 1.0 support to distinguish from other Go AMQP clients supporting
draft versions of AMQP.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/b64d0fa6
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/b64d0fa6
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/b64d0fa6
Branch: refs/heads/go1
Commit: b64d0fa630f81d58f69f844856818dd2ba315807
Parents: 7b6b8de
Author: Alan Conway <ac...@redhat.com>
Authored: Tue Nov 1 23:17:07 2016 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Tue Nov 1 23:17:07 2016 -0400
----------------------------------------------------------------------
proton-c/bindings/go/src/qpid.apache.org/amqp/doc.go | 6 ++++--
.../bindings/go/src/qpid.apache.org/electron/doc.go | 3 +--
proton-c/bindings/go/src/qpid.apache.org/proton/doc.go | 13 +++++--------
3 files changed, 10 insertions(+), 12 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b64d0fa6/proton-c/bindings/go/src/qpid.apache.org/amqp/doc.go
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/qpid.apache.org/amqp/doc.go b/proton-c/bindings/go/src/qpid.apache.org/amqp/doc.go
index 323c344..97051a5 100644
--- a/proton-c/bindings/go/src/qpid.apache.org/amqp/doc.go
+++ b/proton-c/bindings/go/src/qpid.apache.org/amqp/doc.go
@@ -18,13 +18,15 @@ under the License.
*/
/*
-Package amqp encodes and decodes AMQP messages and data types as Go types.
+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.
-AMQP is an open standard for inter-operable message exchange, see <http://www.amqp.org/>
+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
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b64d0fa6/proton-c/bindings/go/src/qpid.apache.org/electron/doc.go
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/qpid.apache.org/electron/doc.go b/proton-c/bindings/go/src/qpid.apache.org/electron/doc.go
index 436e5df..bc2c589 100644
--- a/proton-c/bindings/go/src/qpid.apache.org/electron/doc.go
+++ b/proton-c/bindings/go/src/qpid.apache.org/electron/doc.go
@@ -18,8 +18,7 @@ under the License.
*/
/*
-Package electron is a procedural, concurrent-safe Go library for AMQP messaging.
-You can write clients and servers using this library.
+Package electron lets you write concurrent AMQP 1.0 messaging clients and servers.
Start by creating a Container with NewContainer. An AMQP Container represents a
single AMQP "application" and can contain client and server connections.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b64d0fa6/proton-c/bindings/go/src/qpid.apache.org/proton/doc.go
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/qpid.apache.org/proton/doc.go b/proton-c/bindings/go/src/qpid.apache.org/proton/doc.go
index 51f70f8..87f81f3 100644
--- a/proton-c/bindings/go/src/qpid.apache.org/proton/doc.go
+++ b/proton-c/bindings/go/src/qpid.apache.org/proton/doc.go
@@ -18,14 +18,11 @@ under the License.
*/
/*
-Package proton is an event-driven, concurrent-unsafe Go library for AMQP messaging.
-You can write clients and servers using this library.
-
-This package is a port of the Proton C API into Go (see
-http://qpid.apache.org/proton) Go programmers may find the 'electron' package
-more convenient. qpid.apache.org/electron provides a concurrent-safe API that
-allows you to run procedural loops in arbitrary goroutines rather than
-implementing event handlers that must run in a single goroutine.
+Package proton is a wrapper for the Proton-C library
+(http://qpid.apache.org/proton) which lets you write AMQP 1.0 messaging clients
+and servers. It is event-driven and concurrent-unsafe.
+
+For a more "Go-like" procedural, concurrent-safe toolkit see package 'electron'.
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
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org
[2/2] qpid-proton git commit: PROTON-1338: Go: update package
documentation.
Posted by ac...@apache.org.
PROTON-1338: Go: update package documentation.
Merge branch 'master' into go1 for updated package documentation.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/f405d29a
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/f405d29a
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/f405d29a
Branch: refs/heads/go1
Commit: f405d29a5b0603ab37237bd605367e248a61068b
Parents: 287eeac b64d0fa
Author: Alan Conway <ac...@redhat.com>
Authored: Tue Nov 1 23:18:47 2016 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Tue Nov 1 23:18:47 2016 -0400
----------------------------------------------------------------------
amqp/doc.go | 6 ++++--
electron/doc.go | 3 +--
proton/doc.go | 13 +++++--------
3 files changed, 10 insertions(+), 12 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/f405d29a/amqp/doc.go
----------------------------------------------------------------------
diff --cc amqp/doc.go
index 323c344,0000000..97051a5
mode 100644,000000..100644
--- a/amqp/doc.go
+++ b/amqp/doc.go
@@@ -1,34 -1,0 +1,36 @@@
+/*
+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 messages and data types as Go types.
++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.
+
- AMQP is an open standard for inter-operable message exchange, see <http://www.amqp.org/>
++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/f405d29a/electron/doc.go
----------------------------------------------------------------------
diff --cc electron/doc.go
index 436e5df,0000000..bc2c589
mode 100644,000000..100644
--- a/electron/doc.go
+++ b/electron/doc.go
@@@ -1,72 -1,0 +1,71 @@@
+/*
+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 is a procedural, concurrent-safe Go library for AMQP messaging.
- You can write clients and servers using this library.
++Package electron lets you write concurrent AMQP 1.0 messaging clients and servers.
+
+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/f405d29a/proton/doc.go
----------------------------------------------------------------------
diff --cc proton/doc.go
index 51f70f8,0000000..87f81f3
mode 100644,000000..100644
--- a/proton/doc.go
+++ b/proton/doc.go
@@@ -1,70 -1,0 +1,67 @@@
+/*
+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 is an event-driven, concurrent-unsafe Go library for AMQP messaging.
- You can write clients and servers using this library.
-
- This package is a port of the Proton C API into Go (see
- http://qpid.apache.org/proton) Go programmers may find the 'electron' package
- more convenient. qpid.apache.org/electron provides a concurrent-safe API that
- allows you to run procedural loops in arbitrary goroutines rather than
- implementing event handlers that must run in a single goroutine.
++Package proton is a wrapper for the Proton-C library
++(http://qpid.apache.org/proton) which lets you write AMQP 1.0 messaging clients
++and servers. It is event-driven and concurrent-unsafe.
++
++For a more "Go-like" procedural, concurrent-safe toolkit see package 'electron'.
+
+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: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org