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:18 UTC
[2/2] qpid-proton git commit: PROTON-1338: Go: update package
documentation.
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