Bug 38252

Summary: specification: document protocol layering
Product: dbus Reporter: Simon McVittie <smcv>
Component: coreAssignee: Simon McVittie <smcv>
Status: RESOLVED FIXED QA Contact: Rob Taylor <rob.taylor>
Severity: enhancement    
Priority: medium CC: hp, lennart, walters, will, zeuthen
Version: 1.5Keywords: patch
Hardware: Other   
OS: All   
URL: http://cgit.freedesktop.org/~smcv/dbus/log/?h=type-system-layering-38252
Whiteboard: review?
i915 platform: i915 features:
Attachments: [PATCH 1/8] Upgrade the type system into its own top-level section of the spec
[PATCH 2/8] Split Basic and Container types into subsections, promote "Type Signatures" to be an intro
[PATCH 3/8] Define single complete types in the overview of the type system
[PATCH 4/8] Don't claim that all basic types work like INT32: strings don't!
[PATCH 5/8] Define the fixed and string-like types a bit more formally
[PATCH 6/8] Promote the definition of valid object paths and signatures into the type system
[PATCH 7/8] Promote the marshalling format to a top-level section
[PATCH 8/8] Describe how to marshal arrays, structs, dict-entries, variants in prose

Description Simon McVittie 2011-06-13 07:40:16 UTC
The lower layers of the spec (type system, marshalling format, messages) are rather mixed up, and the definition of "single complete type" should be more prominent.

Other improvements in this branch (which I will admit has suffered from some scope-creep):

* include mnemonics for the type characters of x, t and h

* explicitly disallow Unicode non-characters (see thread
  http://lists.freedesktop.org/archives/dbus/2010-February/012182.html
  where this was the consensus)

* explicitly say that the trailing NUL is not conceptually part of the string,
  but is part of the marshalling format (it's not part of the length, we
  include it to be nice to C)

* pull out the details of container marshalling from the Great Big Table
  and turn them into prose; keep the Great Big Table as a summary
Comment 1 Simon McVittie 2011-06-13 07:41:30 UTC
Created attachment 47896 [details] [review]
[PATCH 1/8] Upgrade the type system into its own top-level section  of the spec

The type system can be used independently, for instance in GVariant
(although GVariant's binary encoding is in fact not the same).
Comment 2 Simon McVittie 2011-06-13 07:41:48 UTC
Created attachment 47897 [details] [review]
[PATCH 2/8] Split Basic and Container types into subsections,  promote "Type Signatures" to be an intro

The "Type Signatures" subsection is basically an introduction to the
type system, so it doesn't need a heading of its own.
Comment 3 Simon McVittie 2011-06-13 07:42:05 UTC
Created attachment 47898 [details] [review]
[PATCH 3/8] Define single complete types in the overview of the type  system
Comment 4 Simon McVittie 2011-06-13 07:42:23 UTC
Created attachment 47899 [details] [review]
[PATCH 4/8] Don't claim that all basic types work like INT32:  strings don't!
Comment 5 Simon McVittie 2011-06-13 07:42:50 UTC
Created attachment 47900 [details] [review]
[PATCH 5/8] Define the fixed and string-like types a bit more  formally
Comment 6 Simon McVittie 2011-06-13 07:43:10 UTC
Created attachment 47901 [details] [review]
[PATCH 6/8] Promote the definition of valid object paths and  signatures into the type system

Also remove the (double!) requirement that signatures be nul-terminated,
and turn it into a note about the marshalling format.
Comment 7 Simon McVittie 2011-06-13 07:43:26 UTC
Created attachment 47902 [details] [review]
[PATCH 7/8] Promote the marshalling format to a top-level section
Comment 8 Simon McVittie 2011-06-13 07:43:44 UTC
Created attachment 47903 [details] [review]
[PATCH 8/8] Describe how to marshal arrays, structs, dict-entries,  variants in prose
Comment 9 Lennart Poettering 2011-07-27 18:06:01 UTC
(In reply to comment #1)
> Created an attachment (id=47896) [details]
> [PATCH 1/8] Upgrade the type system into its own top-level section  of the spec
> 
> The type system can be used independently, for instance in GVariant
> (although GVariant's binary encoding is in fact not the same).

Looks good. BTW: Isn't "marshalling" more correct than "marshaling"? I mean it's "labelling" and not "labeling", right?
Comment 10 Simon McVittie 2011-07-28 03:02:33 UTC
(In reply to comment #9)
> BTW: Isn't "marshalling" more correct than "marshaling"?

FOLDOC claims that "marshalling" is correct en_GB, and both are correct en_US. After this branch has been merged, I'd be more than happy to apply British English spellings if people prefer them :-)
Comment 11 Simon McVittie 2011-07-28 04:22:54 UTC
(In reply to comment #9)
> (In reply to comment #1)
> > [PATCH 1/8] [...]
> 
> Looks good.

Thanks, merged for 1.5.6. Any thoughts on the other 7 patches? (Or was this intended as positive review of all 8?)
Comment 12 Simon McVittie 2012-03-12 05:10:30 UTC
(In reply to comment #11)
> > > [PATCH 1/8] [...]
> 
> Thanks, merged for 1.5.6. Any thoughts on the other 7 patches? (Or was this
> intended as positive review of all 8?)

Ping? I'd like to get this merged, spec clarity is a good thing.
Comment 13 Simon McVittie 2012-06-05 03:55:26 UTC
(In reply to comment #12)
> Ping? I'd like to get this merged, spec clarity is a good thing.

This has now missed the boat for 1.6. How about 1.7?
Comment 14 Will Thompson 2012-06-07 08:14:49 UTC
Comment on attachment 47897 [details] [review]
[PATCH 2/8] Split Basic and Container types into subsections,  promote "Type Signatures" to be an intro

Review of attachment 47897 [details] [review]:
-----------------------------------------------------------------

Looks fine.
Comment 15 Will Thompson 2012-06-07 08:15:31 UTC
Comment on attachment 47898 [details] [review]
[PATCH 3/8] Define single complete types in the overview of the type  system

Review of attachment 47898 [details] [review]:
-----------------------------------------------------------------

Looks fine.
Comment 16 Will Thompson 2012-06-07 08:18:26 UTC
Comment on attachment 47899 [details] [review]
[PATCH 4/8] Don't claim that all basic types work like INT32:  strings don't!

Review of attachment 47899 [details] [review]:
-----------------------------------------------------------------

Looks good.
Comment 17 Will Thompson 2012-06-07 08:19:54 UTC
Comment on attachment 47900 [details] [review]
[PATCH 5/8] Define the fixed and string-like types a bit more  formally

Review of attachment 47900 [details] [review]:
-----------------------------------------------------------------

I guess this slightly duplicates information from the two big tables, but that's not necessarily a bad thing.
Comment 18 Will Thompson 2012-06-07 08:21:24 UTC
Comment on attachment 47901 [details] [review]
[PATCH 6/8] Promote the definition of valid object paths and  signatures into the type system

Review of attachment 47901 [details] [review]:
-----------------------------------------------------------------

Fine.
Comment 19 Will Thompson 2012-06-07 08:23:21 UTC
Comment on attachment 47902 [details] [review]
[PATCH 7/8] Promote the marshalling format to a top-level section

Review of attachment 47902 [details] [review]:
-----------------------------------------------------------------

Looks good.
Comment 20 Will Thompson 2012-06-07 08:23:24 UTC
Comment on attachment 47903 [details] [review]
[PATCH 8/8] Describe how to marshal arrays, structs, dict-entries,  variants in prose

Review of attachment 47903 [details] [review]:
-----------------------------------------------------------------

Also looks good.
Comment 21 Simon McVittie 2012-06-15 06:35:36 UTC
Fixed in git for 1.7.0, thanks

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.