From 4959a92385e2a6d7a4b8419784f85e5762c714cf Mon Sep 17 00:00:00 2001 From: Triton Circonflexe Date: Tue, 7 Jun 2022 21:40:41 +0200 Subject: THRIFT-5592 Add uuid type documentation Patch: Triton Circonflexe Also includes followup-patch for THRIFT-5588 Remove references to slist and senum from docs This closes #2618 --- doc/specs/idl.md | 70 +++++++++++++++++------------------- doc/specs/thrift-binary-protocol.md | 10 ++++++ doc/specs/thrift-compact-protocol.md | 11 ++++++ doc/specs/thrift-protocol-spec.md | 1 + 4 files changed, 54 insertions(+), 38 deletions(-) (limited to 'doc') diff --git a/doc/specs/idl.md b/doc/specs/idl.md index 1c6a94a83..7ae1af83d 100644 --- a/doc/specs/idl.md +++ b/doc/specs/idl.md @@ -42,7 +42,7 @@ A namespace declares which namespaces/package/module/etc. the type definitions i ## Definition - [7] Definition ::= Const | Typedef | Enum | Senum | Struct | Union | Exception | Service + [7] Definition ::= Const | Typedef | Enum | Struct | Union | Exception | Service ### Const @@ -60,17 +60,11 @@ An enum creates an enumerated type, with named values. If no constant value is s [10] Enum ::= 'enum' Identifier '{' (Identifier ('=' IntConstant)? ListSeparator?)* '}' -### Senum - -Senum (and Slist) are now deprecated and should both be replaced with String. - - [11] Senum ::= 'senum' Identifier '{' (Literal ListSeparator?)* '}' - ### Struct Structs are the fundamental compositional type in Thrift. The name of each field must be unique within the struct. - [12] Struct ::= 'struct' Identifier 'xsd_all'? '{' Field* '}' + [11] Struct ::= 'struct' Identifier 'xsd_all'? '{' Field* '}' N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no purpose in Thrift itself. Use of this feature is strongly discouraged @@ -78,7 +72,7 @@ N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no Unions are similar to structs, except that they provide a means to transport exactly one field of a possible set of fields, just like union {} in C++. Consequently, union members are implicitly considered optional (see requiredness). - [13] Union ::= 'union' Identifier 'xsd_all'? '{' Field* '}' + [12] Union ::= 'union' Identifier 'xsd_all'? '{' Field* '}' N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no purpose in Thrift itself. Use of this feature is strongly discouraged @@ -86,27 +80,27 @@ N.B.: The `xsd_all` keyword has some purpose internal to Facebook but serves no Exceptions are similar to structs except that they are intended to integrate with the native exception handling mechanisms in the target languages. The name of each field must be unique within the exception. - [14] Exception ::= 'exception' Identifier '{' Field* '}' + [13] Exception ::= 'exception' Identifier '{' Field* '}' ### Service A service provides the interface for a set of functionality provided by a Thrift server. The interface is simply a list of functions. A service can extend another service, which simply means that it provides the functions of the extended service in addition to its own. - [15] Service ::= 'service' Identifier ( 'extends' Identifier )? '{' Function* '}' + [14] Service ::= 'service' Identifier ( 'extends' Identifier )? '{' Function* '}' ## Field - [16] Field ::= FieldID? FieldReq? FieldType Identifier ('=' ConstValue)? XsdFieldOptions ListSeparator? + [15] Field ::= FieldID? FieldReq? FieldType Identifier ('=' ConstValue)? XsdFieldOptions ListSeparator? ### Field ID - [17] FieldID ::= IntConstant ':' + [16] FieldID ::= IntConstant ':' ### Field Requiredness There are two explicit requiredness values, and a third one that is applied implicitly if neither *required* nor *optional* are given: *default* requiredness. - [18] FieldReq ::= 'required' | 'optional' + [17] FieldReq ::= 'required' | 'optional' The general rules for requiredness are as follows: @@ -146,69 +140,69 @@ The major point to keep in mind here is the fact, that any unwritten default val N.B.: These have some internal purpose at Facebook but serve no current purpose in Thrift. The use of these options is strongly discouraged. - [19] XsdFieldOptions ::= 'xsd_optional'? 'xsd_nillable'? XsdAttrs? + [18] XsdFieldOptions ::= 'xsd_optional'? 'xsd_nillable'? XsdAttrs? - [20] XsdAttrs ::= 'xsd_attrs' '{' Field* '}' + [19] XsdAttrs ::= 'xsd_attrs' '{' Field* '}' ## Functions - [21] Function ::= 'oneway'? FunctionType Identifier '(' Field* ')' Throws? ListSeparator? + [20] Function ::= 'oneway'? FunctionType Identifier '(' Field* ')' Throws? ListSeparator? - [22] FunctionType ::= FieldType | 'void' + [21] FunctionType ::= FieldType | 'void' - [23] Throws ::= 'throws' '(' Field* ')' + [22] Throws ::= 'throws' '(' Field* ')' ## Types - [24] FieldType ::= Identifier | BaseType | ContainerType + [23] FieldType ::= Identifier | BaseType | ContainerType - [25] DefinitionType ::= BaseType | ContainerType + [24] DefinitionType ::= BaseType | ContainerType - [26] BaseType ::= 'bool' | 'byte' | 'i8' | 'i16' | 'i32' | 'i64' | 'double' | 'string' | 'binary' | 'slist' + [25] BaseType ::= 'bool' | 'byte' | 'i8' | 'i16' | 'i32' | 'i64' | 'double' | 'string' | 'binary' | 'uuid' - [27] ContainerType ::= MapType | SetType | ListType + [26] ContainerType ::= MapType | SetType | ListType - [28] MapType ::= 'map' CppType? '<' FieldType ',' FieldType '>' + [27] MapType ::= 'map' CppType? '<' FieldType ',' FieldType '>' - [29] SetType ::= 'set' CppType? '<' FieldType '>' + [28] SetType ::= 'set' CppType? '<' FieldType '>' - [30] ListType ::= 'list' '<' FieldType '>' CppType? + [29] ListType ::= 'list' '<' FieldType '>' CppType? - [31] CppType ::= 'cpp_type' Literal + [30] CppType ::= 'cpp_type' Literal ## Constant Values - [32] ConstValue ::= IntConstant | DoubleConstant | Literal | Identifier | ConstList | ConstMap + [31] ConstValue ::= IntConstant | DoubleConstant | Literal | Identifier | ConstList | ConstMap - [33] IntConstant ::= ('+' | '-')? Digit+ + [32] IntConstant ::= ('+' | '-')? Digit+ - [34] DoubleConstant ::= ('+' | '-')? Digit* ('.' Digit+)? ( ('E' | 'e') IntConstant )? + [33] DoubleConstant ::= ('+' | '-')? Digit* ('.' Digit+)? ( ('E' | 'e') IntConstant )? - [35] ConstList ::= '[' (ConstValue ListSeparator?)* ']' + [34] ConstList ::= '[' (ConstValue ListSeparator?)* ']' - [36] ConstMap ::= '{' (ConstValue ':' ConstValue ListSeparator?)* '}' + [35] ConstMap ::= '{' (ConstValue ':' ConstValue ListSeparator?)* '}' ## Basic Definitions ### Literal - [37] Literal ::= ('"' [^"]* '"') | ("'" [^']* "'") + [36] Literal ::= ('"' [^"]* '"') | ("'" [^']* "'") ### Identifier - [38] Identifier ::= ( Letter | '_' ) ( Letter | Digit | '.' | '_' )* + [37] Identifier ::= ( Letter | '_' ) ( Letter | Digit | '.' | '_' )* - [39] STIdentifier ::= ( Letter | '_' ) ( Letter | Digit | '.' | '_' | '-' )* + [38] STIdentifier ::= ( Letter | '_' ) ( Letter | Digit | '.' | '_' | '-' )* ### List Separator - [40] ListSeparator ::= ',' | ';' + [39] ListSeparator ::= ',' | ';' ### Letters and Digits - [41] Letter ::= ['A'-'Z'] | ['a'-'z'] + [40] Letter ::= ['A'-'Z'] | ['a'-'z'] - [42] Digit ::= ['0'-'9'] + [41] Digit ::= ['0'-'9'] ## Reserved keywords diff --git a/doc/specs/thrift-binary-protocol.md b/doc/specs/thrift-binary-protocol.md index 4284328e5..af4bd8196 100644 --- a/doc/specs/thrift-binary-protocol.md +++ b/doc/specs/thrift-binary-protocol.md @@ -87,6 +87,15 @@ encode the int64 in 8 bytes in big endian order. Values of `bool` type are first converted to an int8. True is converted to `1`, false to `0`. +### Universal unique identifier encoding + +Values of `uuid` type are expected as 16-byte binary in big endian (or "network") order. Byte order conversion +might be necessary on certain platforms, e.g. Windows holds GUIDs in a complex record-like structure whose +memory layout differs. + +*Note*: Since the length is fixed, no `byte length` prefix is necessary and the field is always 16 bytes long. + + ## Message A `Message` can be encoded in two different ways: @@ -192,6 +201,7 @@ The following field-types are used: * `MAP`, encoded as `13` * `SET`, encoded as `14` * `LIST`, encoded as `15` +* `UUID`, encoded as `16` ## List and Set diff --git a/doc/specs/thrift-compact-protocol.md b/doc/specs/thrift-compact-protocol.md index 07cc5626e..a31a2d329 100644 --- a/doc/specs/thrift-compact-protocol.md +++ b/doc/specs/thrift-compact-protocol.md @@ -120,6 +120,15 @@ Booleans are encoded differently depending on whether it is a field value (in a list or map). Field values are encoded directly in the field header. Element values of type `bool` are sent as an int8; true as `1` and false as `0`. +### Universal unique identifier encoding + +Values of `uuid` type are expected as 16-byte binary in big endian (or "network") order. Byte order conversion +might be necessary on certain platforms, e.g. Windows holds GUIDs in a complex record-like structure whose +memory layout differs. + +*Note*: Since the length is fixed, no `byte length` prefix is necessary and the field is always 16 bytes long. + + ## Message A `Message` on the wire looks as follows: @@ -215,6 +224,7 @@ The following field-types can be encoded: * `SET`, encoded as `10` * `MAP`, encoded as `11` * `STRUCT`, used for both structs and union fields, encoded as `12` +* `UUID`, encoded as `13` Note that because there are 2 specific field types for the boolean values, the encoding of a boolean field value has no length (0 bytes). @@ -258,6 +268,7 @@ The following element-types are used (see note below): * `SET`, encoded as `10` * `MAP`, encoded as `11` * `STRUCT`, used for structs and union fields, encoded as `12` +* `UUID`, encoded as `13` *Note*: Although field-types and element-types lists are currently very similar, there is _no guarantee_ that this will remain true after new types are added. diff --git a/doc/specs/thrift-protocol-spec.md b/doc/specs/thrift-protocol-spec.md index 080487e1b..4b0efafee 100644 --- a/doc/specs/thrift-protocol-spec.md +++ b/doc/specs/thrift-protocol-spec.md @@ -67,6 +67,7 @@ of a function, or an exception. ::= T_BOOL | T_BYTE | T_I8 | T_I16 | T_I32 | T_I64 | T_DOUBLE | T_STRING | T_BINARY | T_STRUCT | T_MAP | T_SET | T_LIST + | T_UUID ::= I16 -- cgit v1.2.1