Skip to content

Commit 05baf19

Browse files
LogofileLogofile
authored
Merge pull request #33 from Logofile/sync
Project import generated by Copybara.
2 parents 5a53c41 + abaf63f commit 05baf19

File tree

8 files changed

+322
-409
lines changed

8 files changed

+322
-409
lines changed

‎config.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -79,7 +79,7 @@ weight = 1
7979
# See a complete list of available styles at https://xyproto.github.io/splash/docs/all.html
8080
style = "tango"
8181
# Uncomment if you want your chosen highlight style used for code blocks without a specified language
82-
# guessSyntax = "true"
82+
guessSyntax = "true"
8383

8484
# Everything below this are Site Params
8585

‎content/programming-guides/proto.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1634,6 +1634,49 @@ Also, note that each option type (file-level, message-level, field-level, etc.)
16341634
has its own number space, so, for example, you could declare extensions of
16351635
FieldOptions and MessageOptions with the same number.
16361636

1637+
### Option Retention {#option-retention}
1638+
1639+
Options have a notion of *retention*, which controls whether an option is
1640+
retained in the generated code. Options have *runtime retention* by default,
1641+
meaning that they are retained in the generated code and are thus visible at
1642+
runtime in the generated descriptor pool. However, you can set `retention =
1643+
RETENTION_SOURCE` to specify that an option (or field within an option) must not
1644+
be retained at runtime. This is called *source retention*.
1645+
1646+
Option retention is an advanced feature that most users should not need to worry
1647+
about, but it can be useful if you would like to use certain options without
1648+
paying the code size cost of retaining them in your binaries. Options with
1649+
source retention are still visible to `protoc` and `protoc` plugins, so code
1650+
generators can use them to customize their behavior.
1651+
1652+
Retention can be set directly on an option, like this;
1653+
1654+
```proto
1655+
extend google.protobuf.FileOptions {
1656+
optional int32 source_retention_option = 1234
1657+
[retention = RETENTION_SOURCE];
1658+
}
1659+
```
1660+
1661+
It can also be set on a plain field, in which case it takes effect only when
1662+
that field appears inside an option:
1663+
1664+
```proto
1665+
message OptionsMessage {
1666+
optional int32 source_retention_field = 1 [retention = RETENTION_SOURCE];
1667+
}
1668+
```
1669+
1670+
You can set `retention = RETENTION_RUNTIME` if you like, but this has no effect
1671+
since it is the default behavior. When a message field is marked
1672+
`RETENTION_SOURCE`, its entire contents are dropped; fields inside it cannot
1673+
override that by trying to set `RETENTION_RUNTIME`.
1674+
1675+
{{% alert title="Note" color="note" %}} As
1676+
of Protocol Buffers 22.0, support for option retention is still in progress and
1677+
only C++ and Java are supported. In all other languages, options are always
1678+
retained at runtime. {{% /alert %}}
1679+
16371680
## Generating Your Classes {#generating}
16381681

16391682
To generate the Java, Python, or C++ code you need to work with the message

‎content/programming-guides/proto3.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1599,6 +1599,49 @@ for details. Note that creating custom options uses
15991599
[extensions](/programming-guides/proto#extensions), which
16001600
are permitted only for custom options in proto3.
16011601
1602+
### Option Retention {#option-retention}
1603+
1604+
Options have a notion of *retention*, which controls whether an option is
1605+
retained in the generated code. Options have *runtime retention* by default,
1606+
meaning that they are retained in the generated code and are thus visible at
1607+
runtime in the generated descriptor pool. However, you can set `retention =
1608+
RETENTION_SOURCE` to specify that an option (or field within an option) must not
1609+
be retained at runtime. This is called *source retention*.
1610+
1611+
Option retention is an advanced feature that most users should not need to worry
1612+
about, but it can be useful if you would like to use certain options without
1613+
paying the code size cost of retaining them in your binaries. Options with
1614+
source retention are still visible to `protoc` and `protoc` plugins, so code
1615+
generators can use them to customize their behavior.
1616+
1617+
Retention can be set directly on an option, like this;
1618+
1619+
```proto
1620+
extend google.protobuf.FileOptions {
1621+
optional int32 source_retention_option = 1234
1622+
[retention = RETENTION_SOURCE];
1623+
}
1624+
```
1625+
1626+
It can also be set on a plain field, in which case it takes effect only when
1627+
that field appears inside an option:
1628+
1629+
```proto
1630+
message OptionsMessage {
1631+
optional int32 source_retention_field = 1 [retention = RETENTION_SOURCE];
1632+
}
1633+
```
1634+
1635+
You can set `retention = RETENTION_RUNTIME` if you like, but this has no effect
1636+
since it is the default behavior. When a message field is marked
1637+
`RETENTION_SOURCE`, its entire contents are dropped; fields inside it cannot
1638+
override that by trying to set `RETENTION_RUNTIME`.
1639+
1640+
{{% alert title="Note" color="note" %}} As
1641+
of Protocol Buffers 22.0, support for option retention is still in progress and
1642+
only C++ and Java are supported. In all other languages, options are always
1643+
retained at runtime. {{% /alert %}}
1644+
16021645
## Generating Your Classes {#generating}
16031646

16041647
To generate the Java, Kotlin, Python, C++, Go, Ruby, Objective-C, or C# code you

‎content/reference/cpp/arenas.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,15 @@ suitable granularity at which to use arenas (for servers, this is often
4444
per-request). You can find out more about how to get the most from arena
4545
allocation in [Usage patterns and best practices](#usage).
4646

47+
This table summarizes the typical performance advantages and disadvantages of
48+
using arenas:
49+
50+
Operation | Heap-allocated proto messages | Arena-allocated proto messages
51+
:-------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :-----------------------------
52+
*Message allocation* | Slower on average | Faster on average
53+
*Message destruction* | Slower on average | Faster on average
54+
*Message moves* | Always a move (equivalent to a [shallow copy](https://en.wikipedia.org/wiki/Object_copying#Shallow_copy) in cost) | Sometimes a [deep copy](https://en.wikipedia.org/wiki/Object_copying#Deep_copy)
55+
4756
## Getting Started {#gettingstarted}
4857

4958
The protocol buffer compiler generates code for arena allocation for the

‎content/support/_index.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: "Support"
3+
weight: 900
4+
toc_hide: false
5+
linkTitle: "Support"
6+
no_list: "true"
7+
type: docs
8+
description: "Get the latest news about Protocol Buffers."
9+
---
10+
11+
12+
This section of the documentation contains topics related to the support that
13+
the Protocol Buffers team provides to developers, including the timeframes for
14+
support for each version of a language library and migration guides to help you
15+
keep up with major version bumps.
16+
17+
<!-- mdformat off(mdformat adds a space before the external tag) -->
18+
* [Version Support](/support/version-support)
19+
* [Migration Guide](/support/migration)
20+
* [Cross-Version Runtime Guarantee](/support/cross-version-runtime-guarantee)
21+
* [Support Forum](https://groups.google.com/g/protobuf)
22+
<!-- mdformat on -->

‎content/support/cross-version-runtime-guarantee.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: "Cross-Version Runtime Guarantee"
3+
weight: 930
4+
toc_hide: false
5+
linkTitle: "Cross-Version Runtime Guarantee"
6+
no_list: "true"
7+
type: docs
8+
description: "The guarantees that the language has for cross-version runtime compatibility."
9+
---
10+
11+
12+
<link rel="stylesheet" href="/includes/version-tables.css">
13+
14+
Protobuf language bindings have two components. The generated code (typically
15+
produced from `protoc`) and the runtime libraries that must be included when
16+
using the generated code. When these come from different releases of protobuf,
17+
we are in a "cross version runtime" situation.
18+
19+
Historically, protobuf has not documented its cross-version runtime
20+
compatibility guarantees and has been inconsistent about enforcing what
21+
guarantees it provides. Moving forward, we intend to offer the following
22+
guarantees across all languages except C++. These are the default guarantees;
23+
however, owners of protobuf code generators and runtimes may explicitly override
24+
them with more specific guarantees for that language.
25+
26+
## Major Versions {#major}
27+
28+
Protobuf will not support mixing generated code and runtimes across major
29+
version boundaries. We will add “poison pills” where possible to detect these
30+
mismatches.
31+
32+
## Minor Versions {#minor}
33+
34+
Within a single major runtime version, generated code from an older version of
35+
`protoc` will run on a newer runtime.
36+
37+
Within a single major runtime version, generated code from a newer version of
38+
`protoc` is not guaranteed to run on an older runtime. We will add “poison
39+
pills” where possible to detect these mismatches.
40+
41+
## Security Exception {#exception}
42+
43+
We reserve the right to violate the above promises if needed for security
44+
reasons. We expect these exceptions to be rare, but will always prioritize
45+
security above these guarantees. For example,
46+
[footmitten](https://cve.report/CVE-2022-3510) required paired updates to both
47+
the runtime and the generated code for Java. As a result, code generated by
48+
3.20.3 (which contained the footmitten fix) would not load with runtime library
49+
3.21.6 (which predates the footmitten fix), creating the following compatibility
50+
matrix:
51+
52+
<table>
53+
<tr>
54+
<td colspan="2" rowspan="2"></td>
55+
<td colspan="4">Generated Code Version</td>
56+
</tr>
57+
<tr>
58+
<td class="gray">3.20.2</td>
59+
<td class="gray">3.20.3</td>
60+
<td class="gray">3.21.6</td>
61+
<td class="gray">3.21.7</td>
62+
</tr>
63+
<tr>
64+
<td rowspan="4">Runtime<br>Version</td>
65+
<td class="gray">3.20.2</td>
66+
<td class="yellow">Vuln</td>
67+
<td class="red"><b>Broken</b></td>
68+
<td class="yellow"><b>Vuln</b></td>
69+
<td class="red"><b>Broken</b></td>
70+
</tr>
71+
<tr>
72+
<td class="gray">3.20.3</td>
73+
<td class="yellow">Vuln</td>
74+
<td class="green">Works</td>
75+
<td class="yellow"><b>Vuln</b></td>
76+
<td class="green"><b>Works?</b></td>
77+
</tr>
78+
<tr>
79+
<td class="gray">3.21.6</td>
80+
<td class="yellow">Vuln</td>
81+
<td class="red">Broken</td>
82+
<td class="yellow">Vuln</td>
83+
<td class="red"><b>Broken</b></td>
84+
</tr>
85+
<tr>
86+
<td class="gray">3.21.7</td>
87+
<td class="yellow">Vuln</td>
88+
<td class="green">Works</td>
89+
<td class="yellow">Vuln</td>
90+
<td class="green">Works</td>
91+
</tr>
92+
</table>
93+
94+
* “Vuln” indicates that the combination will successfully start, but the
95+
security vulnerability still exists.
96+
* “Works” indicates that the combination will successfully start and does not
97+
have the vulnerability.
98+
* “Broken” indicates that the combination will not successfully start.
99+
* **Bold** indicates configurations that were never deliberately intended to
100+
function together given the guarantees outlined in this topic.
101+
102+
## No Coexistence of Multiple Major Runtime Versions {#coexist}
103+
104+
Coexistence of multiple major versions in the same process is **not** supported.
105+
106+
## C++ Specific Guarantees {#cpp}
107+
108+
Protobuf C++ disclaims all cross-runtime support and requires an exact match
109+
between its generated code version and its runtime version at all times.
110+
Additionally, Protobuf C++ makes no guarantees about ABI stability across any
111+
releases (major, minor, or micro).

content/programming-guides/migration.md renamed to content/support/migration.md

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
11
---
22
title: "Migration Guide"
3-
weight: 1040
3+
weight: 920
44
toc_hide: false
55
linkTitle: "Migration Guide"
66
no_list: "true"
77
type: docs
88
description: "A list of the breaking changes made to versions of the libraries, and how to update your code to accommodate the changes."
9+
aliases:
10+
- /programming-guides/migration/
911
---
1012

1113
This topic provides information about breaking changes in Protocol Buffers, and

0 commit comments

Comments
 (0)