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 2015/03/02 16:13:58 UTC
qpid-proton git commit: PROTON-827: Updated README,
added copyright comments.
Repository: qpid-proton
Updated Branches:
refs/heads/master 4b5796df4 -> 3f596d99f
PROTON-827: Updated README, added copyright comments.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/3f596d99
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/3f596d99
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/3f596d99
Branch: refs/heads/master
Commit: 3f596d99f66ced2c9c9a745d9d4f2b39825f76d1
Parents: 4b5796d
Author: Alan Conway <ac...@redhat.com>
Authored: Sun Mar 1 22:04:12 2015 -0500
Committer: Alan Conway <ac...@redhat.com>
Committed: Mon Mar 2 10:10:31 2015 -0500
----------------------------------------------------------------------
proton-c/bindings/go/README.md | 104 ++++++++++---------
.../bindings/go/src/apache.org/proton/doc.go | 22 ++++
.../bindings/go/src/apache.org/proton/url.go | 19 ++++
.../go/src/apache.org/proton/url_test.go | 19 ++++
4 files changed, 115 insertions(+), 49 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/3f596d99/proton-c/bindings/go/README.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/README.md b/proton-c/bindings/go/README.md
index d2c8efe..fbe61e5 100644
--- a/proton-c/bindings/go/README.md
+++ b/proton-c/bindings/go/README.md
@@ -2,6 +2,31 @@
This is the (very early) beginning of a go binding for proton.
+## Goals
+
+The API will be inspired by the reactive, event-driven python API. Key features
+to preserve:
+
+- support client and server development.
+- incremental composition of functionality via handlers.
+- default handlers to make simple tasks simple.
+- deep access to AMQP protocol events when that is required.
+
+The API will be idiomatic, unsurprising, and easy to use for Go developers.
+
+There are two types of developer we want to support
+
+1. For 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. For AMQP-aware developers using Go as an implementation language:
+ - Go types to exactly represent all AMQP types and encoding details.
+ - Full access to AMQP concepts like connections, sessions and links via handler interfaces.
+
+We will follow conventions of the C and python API where possible to help
+multi-language developers but idiomatic Go is the overriding consideration.
+
## Layout
The plan is to adopt standard Go tools and practices, see the <http://golang.org>
@@ -27,52 +52,7 @@ If you are new to Go (like me) then these are a good place to start:
Then look at the tools and library docs at <http://golang.org> as you need them.
-The docs are short, readable and informative. Even the language specification
-<http://golang.org/ref/spec> is a readable and useful reference.
-
-My first impression is that Go is a little odd but approachable and has some
-very interesting features. I look forward to writing some real code.
-
-Go has simple but effective tools for building, testing, documenting,
-formatting, installing etc. So far I have used `go build`, `go run`, `go test`
-and `godoc`. They all Just Worked with little or no head-scratching. For
-example, within 5 minutes of discovering `godoc` I had a searchable web site on
-my laptop serving all the standard Go docs and the docs for the fledgling
-proton package.
-
-"Simple but effective" seems to be a big part of the Go design philosophy.
-
-## Design of the binding
-
-The API will be based on the design of the reactive python API, some key features to preserve are:
-
-- client and server development.
-- reactive and synchronous programming styles.
-- incremental composition of functionality via handlers.
-- default handlers to make simple tasks simple.
-- deep access to AMQP protocol events when that is required.
-
-Go is it's own language, and we have two goals to balance:
-
-- avoid needless deviation from existing APIs to lower the barrier to move between languages.
-- present an idiomatic, easy-to-use, unsurprising Go API that takes full advantage of Go's features.
-
-The implementation will use `cgo` to call into the proton C reactor and other
-proton C APIs. `cgo` is simpler than Swig, requires only knowledge of Go and C
-and is effortlessly integrated into the Go tools.
-
-Go's use of channels for synchronization present interesting opportunities. Go
-also supports traditional locking, so we could adopt locking strategies similar
-to our other bindings, but we should investigate the Go-like alternatives. There
-are anaolgies between Go channels and AMQP links that we will probably exploit.
-
-## State of the implementation
-
-So far we have a wrapper for `pn_url_t` with unit tests and docs. This just
-gives us an initial workspace and exercies for the tools and establishes the
-basics of using cgo to call into proton code.
-
-Here are some things you can do. First set your environment:
+Here are some things you can try. First set your environment:
export GOPATH=<path to this directory>
@@ -92,7 +72,33 @@ proton docs.
To run the unit tests:
- go test apache.org/proton
+ go test -a apache.org/proton
+
+## Design Notes
+
+### C wrapping philosophy
+
+We use `cgo` to call proton C functions directly. `cgo` is simpler and more
+direct than Swig and integrated into the Go tools.
+
+Calling C directly from Go is so easy that we will avoid low-level 1-1 wrappers
+for proton objects and focus on easy to use Go types that live within Go's
+automatic memory management.
+
+Programmers that need lower-level access than we provide can go direct to C, but
+of course we will aim to make that unnecessary in all but the most unusual cases.
+
+### Other considerations
+
+Go's use of channels for synchronization present interesting opportunities. Go
+also supports traditional locking, so we could adopt locking strategies similar
+to our other bindings, but we should investigate the Go-like alternatives. There
+are analogies between Go channels and AMQP links that we will probably exploit.
+
+## State of the implementation
+
+So far we have a wrapper for `pn_url_t` with unit tests and docs. This just
+gives us an initial work-space and exercise for the tools and establishes the
+basics of using cgo to call into proton code.
+
-All feedback most gratefully received especially from experience Go programmers
-on issues of style, use of the language or use of the tools.
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/3f596d99/proton-c/bindings/go/src/apache.org/proton/doc.go
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/apache.org/proton/doc.go b/proton-c/bindings/go/src/apache.org/proton/doc.go
index f633d3c..34f85fe 100644
--- a/proton-c/bindings/go/src/apache.org/proton/doc.go
+++ b/proton-c/bindings/go/src/apache.org/proton/doc.go
@@ -1,10 +1,32 @@
/*
+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 a Go binding for the proton AMQP protocol engine.
It alows you to construct and parse AMQP messages, and to implement AMQP
clients, servers and intermediaries that can exchange messages with any
AMQP 1.0 compliant endpoint.
+Encoding and decoding AMQP data follows the pattern of the standard
+encoding/json and encoding/xml packages.The mapping between AMQP and Go types is
+described in the documentation of the Marshal and Unmarshal functions.
*/
package proton
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/3f596d99/proton-c/bindings/go/src/apache.org/proton/url.go
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/apache.org/proton/url.go b/proton-c/bindings/go/src/apache.org/proton/url.go
index 2304814..9c76b7d 100644
--- a/proton-c/bindings/go/src/apache.org/proton/url.go
+++ b/proton-c/bindings/go/src/apache.org/proton/url.go
@@ -1,3 +1,22 @@
+/*
+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
/*
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/3f596d99/proton-c/bindings/go/src/apache.org/proton/url_test.go
----------------------------------------------------------------------
diff --git a/proton-c/bindings/go/src/apache.org/proton/url_test.go b/proton-c/bindings/go/src/apache.org/proton/url_test.go
index 1c3128a..3174769 100644
--- a/proton-c/bindings/go/src/apache.org/proton/url_test.go
+++ b/proton-c/bindings/go/src/apache.org/proton/url_test.go
@@ -1,3 +1,22 @@
+/*
+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
import (
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org