Skip to content

Commit 150aa03

Browse files
ChocoLZSChocoLZS
committed
doc: unify comments
1 parent 8afe1d0 commit 150aa03

8 files changed

Lines changed: 78 additions & 54 deletions

File tree

‎pkg/rpcinfo/ctx.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -45,9 +45,11 @@ func GetRPCInfo(ctx context.Context) RPCInfo {
4545

4646
// PutRPCInfo recycles the RPCInfo. This function is for internal use only.
4747
//
48-
// Deprecated: RPCInfo recycling may cause panic when RPCInfo is accessed
49-
// asynchronously after it has been recycled. Kitex is gradually migrating away
50-
// from RPCInfo pooling and will remove this pooling mechanism in the future.
48+
// Deprecated: RPCInfo recycling is part of the legacy RPCInfo pooling mechanism
49+
// under migration. It may cause panic or data races when RPCInfo is accessed
50+
// asynchronously after framework cleanup. Kitex is gradually removing this
51+
// pooling mechanism; this function is kept only for compatibility during the
52+
// migration.
5153
func PutRPCInfo(ri RPCInfo) {
5254
if v, ok := ri.(internal.Reusable); ok {
5355
v.Recycle()

‎pkg/rpcinfo/endpointInfo.go‎

Lines changed: 10 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -22,12 +22,13 @@ import (
2222
)
2323

2424
var (
25-
_ EndpointInfo = &endpointInfo{}
26-
_ MutableEndpointInfo = &endpointInfo{}
25+
_ EndpointInfo = &endpointInfo{}
26+
_ MutableEndpointInfo = &endpointInfo{}
2727

2828
// Deprecated: endpointInfo pooling is part of the legacy RPCInfo pooling
29-
// mechanism. When RPCInfo pooling is disabled, framework-owned endpointInfo
30-
// objects are no longer put back through the RPCInfo lifecycle.
29+
// mechanism under migration. RPCInfo pooling may cause panic or data races
30+
// when RPCInfo is accessed asynchronously after framework cleanup. Kitex is
31+
// gradually removing this pooling mechanism.
3132
endpointPool sync.Pool
3233
)
3334

@@ -139,10 +140,11 @@ func (ei *endpointInfo) zero() {
139140

140141
// Recycle is used to recycle the endpointInfo.
141142
//
142-
// Deprecated: endpointInfo recycling is part of the RPCInfo pooling mechanism,
143-
// which may cause panic when RPCInfo is accessed asynchronously after it has
144-
// been recycled. Kitex is gradually migrating away from RPCInfo pooling and will
145-
// remove this pooling mechanism in the future.
143+
// Deprecated: endpointInfo recycling is part of the legacy RPCInfo pooling
144+
// mechanism under migration. It may cause panic or data races when RPCInfo is
145+
// accessed asynchronously after framework cleanup. Kitex is gradually removing
146+
// this pooling mechanism; this method is kept only for compatibility during the
147+
// migration.
146148
func (ei *endpointInfo) Recycle() {
147149
ei.zero()
148150
endpointPool.Put(ei)

‎pkg/rpcinfo/invocation.go‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,9 @@ var (
3434
_ InvocationSetter = (*invocation)(nil)
3535

3636
// Deprecated: invocation pooling is part of the legacy RPCInfo pooling
37-
// mechanism. When RPCInfo pooling is disabled, framework-owned invocations
38-
// are no longer put back through the RPCInfo lifecycle.
37+
// mechanism under migration. RPCInfo pooling may cause panic or data races
38+
// when RPCInfo is accessed asynchronously after framework cleanup. Kitex is
39+
// gradually removing this pooling mechanism.
3940
invocationPool sync.Pool
4041
globalSeqID int32 = 0
4142
)
@@ -201,10 +202,11 @@ func (i *invocation) Reset() {
201202

202203
// Recycle reuses the invocation.
203204
//
204-
// Deprecated: invocation recycling is part of the RPCInfo pooling mechanism,
205-
// which may cause panic when RPCInfo is accessed asynchronously after it has
206-
// been recycled. Kitex is gradually migrating away from RPCInfo pooling and will
207-
// remove this pooling mechanism in the future.
205+
// Deprecated: invocation recycling is part of the legacy RPCInfo pooling
206+
// mechanism under migration. It may cause panic or data races when RPCInfo is
207+
// accessed asynchronously after framework cleanup. Kitex is gradually removing
208+
// this pooling mechanism; this method is kept only for compatibility during the
209+
// migration.
208210
func (i *invocation) Recycle() {
209211
i.zero()
210212
invocationPool.Put(i)

‎pkg/rpcinfo/remoteinfo/remoteInfo.go‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,9 @@ var (
5555
_ RemoteInfo = &remoteInfo{}
5656

5757
// Deprecated: remoteInfo pooling is part of the legacy RPCInfo pooling
58-
// mechanism. When RPCInfo pooling is disabled, framework-owned remoteInfo
59-
// objects are no longer put back through the RPCInfo lifecycle.
58+
// mechanism under migration. RPCInfo pooling may cause panic or data races
59+
// when RPCInfo is accessed asynchronously after framework cleanup. Kitex is
60+
// gradually removing this pooling mechanism.
6061
remoteInfoPool sync.Pool
6162
)
6263

@@ -200,10 +201,11 @@ func (ri *remoteInfo) zero() {
200201

201202
// Recycle is used to recycle the remoteInfo.
202203
//
203-
// Deprecated: remoteInfo recycling is part of the RPCInfo pooling mechanism,
204-
// which may cause panic when RPCInfo is accessed asynchronously after it has
205-
// been recycled. Kitex is gradually migrating away from RPCInfo pooling and will
206-
// remove this pooling mechanism in the future.
204+
// Deprecated: remoteInfo recycling is part of the legacy RPCInfo pooling
205+
// mechanism under migration. It may cause panic or data races when RPCInfo is
206+
// accessed asynchronously after framework cleanup. Kitex is gradually removing
207+
// this pooling mechanism; this method is kept only for compatibility during the
208+
// migration.
207209
func (ri *remoteInfo) Recycle() {
208210
if r, ok := ri.instance.(internal.Reusable); ok {
209211
r.Recycle()

‎pkg/rpcinfo/rpcconfig.go‎

Lines changed: 8 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,9 @@ var (
3131
_ RPCConfig = &rpcConfig{}
3232

3333
// Deprecated: rpcConfig pooling is part of the legacy RPCInfo pooling
34-
// mechanism. When RPCInfo pooling is disabled, framework-owned rpcConfig
35-
// objects are no longer put back through the RPCInfo lifecycle.
34+
// mechanism under migration. RPCInfo pooling may cause panic or data races
35+
// when RPCInfo is accessed asynchronously after framework cleanup. Kitex is
36+
// gradually removing this pooling mechanism.
3637
rpcConfigPool sync.Pool
3738
)
3839

@@ -245,10 +246,11 @@ func (r *rpcConfig) initialize() {
245246

246247
// Recycle reuses the rpcConfig.
247248
//
248-
// Deprecated: rpcConfig recycling is part of the RPCInfo pooling mechanism,
249-
// which may cause panic when RPCInfo is accessed asynchronously after it has
250-
// been recycled. Kitex is gradually migrating away from RPCInfo pooling and will
251-
// remove this pooling mechanism in the future.
249+
// Deprecated: rpcConfig recycling is part of the legacy RPCInfo pooling
250+
// mechanism under migration. It may cause panic or data races when RPCInfo is
251+
// accessed asynchronously after framework cleanup. Kitex is gradually removing
252+
// this pooling mechanism; this method is kept only for compatibility during the
253+
// migration.
252254
func (r *rpcConfig) Recycle() {
253255
r.initialize()
254256
rpcConfigPool.Put(r)

‎pkg/rpcinfo/rpcinfo.go‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,8 @@ func init() {
3535
}
3636

3737
func initPoolEnabledFromEnv() {
38-
// allow disabling by env without modifying the code and recompiling
38+
// Keep migration-only env switches for compatibility with existing
39+
// deployments while RPCInfo pooling is being phased out.
3940
if os.Getenv("KITEX_DISABLE_RPCINFO_POOL") != "" {
4041
EnablePool(false)
4142
}
@@ -53,9 +54,10 @@ func initPoolEnabledFromEnv() {
5354
// By turning off the pool, we can quickly confirm whether the concurrency issues is
5455
// caused by such cases, but do remember there's a PERFORMANCE LOSS.
5556
//
56-
// Deprecated: RPCInfo pooling may cause panic when RPCInfo is accessed
57-
// asynchronously after it has been recycled. Kitex is gradually migrating away
58-
// from RPCInfo pooling and will remove this pooling mechanism in the future.
57+
// Deprecated: RPCInfo pooling is a legacy mechanism under migration. It may
58+
// cause panic or data races when RPCInfo is accessed asynchronously after
59+
// framework cleanup. Kitex is gradually removing this pooling mechanism; this
60+
// API is kept only for compatibility during the migration.
5961
func EnablePool(enable bool) {
6062
if enable {
6163
atomic.StoreInt32(&enablePool, 1)
@@ -66,9 +68,10 @@ func EnablePool(enable bool) {
6668

6769
// PoolEnabled returns true if rpcInfoPool is enabled.
6870
//
69-
// Deprecated: RPCInfo pooling may cause panic when RPCInfo is accessed
70-
// asynchronously after it has been recycled. Kitex is gradually migrating away
71-
// from RPCInfo pooling and will remove this pooling mechanism in the future.
71+
// Deprecated: RPCInfo pooling is a legacy mechanism under migration. It may
72+
// cause panic or data races when RPCInfo is accessed asynchronously after
73+
// framework cleanup. Kitex is gradually removing this pooling mechanism; this
74+
// API is kept only for compatibility during the migration.
7275
func PoolEnabled() bool {
7376
return atomic.LoadInt32(&enablePool) == 1
7477
}
@@ -106,9 +109,11 @@ func (r *rpcInfo) zero() {
106109

107110
// Recycle reuses the rpcInfo.
108111
//
109-
// Deprecated: RPCInfo recycling may cause panic when RPCInfo is accessed
110-
// asynchronously after it has been recycled. Kitex is gradually migrating away
111-
// from RPCInfo pooling and will remove this pooling mechanism in the future.
112+
// Deprecated: RPCInfo recycling is part of the legacy RPCInfo pooling mechanism
113+
// under migration. It may cause panic or data races when RPCInfo is accessed
114+
// asynchronously after framework cleanup. Kitex is gradually removing this
115+
// pooling mechanism; this method is kept only for compatibility during the
116+
// migration.
112117
func (r *rpcInfo) Recycle() {
113118
if !PoolEnabled() {
114119
return

‎pkg/rpcinfo/rpcinfo_inline.go‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,9 @@ import (
2323
)
2424

2525
// Deprecated: inline RPCInfo pooling is part of the legacy RPCInfo pooling
26-
// mechanism. When RPCInfo pooling is disabled, framework-owned inline RPCInfo
27-
// objects are no longer put back through the RPCInfo lifecycle.
26+
// mechanism under migration. RPCInfo pooling may cause panic or data races when
27+
// RPCInfo is accessed asynchronously after framework cleanup. Kitex is gradually
28+
// removing this pooling mechanism.
2829
var inlineRPCInfoPool sync.Pool
2930

3031
func init() {
@@ -56,9 +57,11 @@ func (r *inlineRPCInfo) Stats() RPCStats { return &r.stats }
5657

5758
// Recycle reuses the inlineRPCInfo.
5859
//
59-
// Deprecated: RPCInfo recycling may cause panic when RPCInfo is accessed
60-
// asynchronously after it has been recycled. Kitex is gradually migrating away
61-
// from RPCInfo pooling and will remove this pooling mechanism in the future.
60+
// Deprecated: RPCInfo recycling is part of the legacy RPCInfo pooling mechanism
61+
// under migration. It may cause panic or data races when RPCInfo is accessed
62+
// asynchronously after framework cleanup. Kitex is gradually removing this
63+
// pooling mechanism; this method is kept only for compatibility during the
64+
// migration.
6265
func (r *inlineRPCInfo) Recycle() {
6366
if !PoolEnabled() {
6467
return
@@ -76,9 +79,11 @@ func (r *inlineRPCInfo) Recycle() {
7679
// The returned RPCInfo's From(), To(), Invocation(), Config(), and Stats() return
7780
// pointers to the inlined fields. Use AsMutable* to modify them after creation.
7881
//
79-
// Deprecated: RPCInfo pooling may cause panic when RPCInfo is accessed
80-
// asynchronously after it has been recycled. Kitex is gradually migrating away
81-
// from RPCInfo pooling and will remove this pooling mechanism in the future.
82+
// Deprecated: inline RPCInfo is part of the legacy RPCInfo pooling mechanism
83+
// under migration. RPCInfo pooling may cause panic or data races when RPCInfo is
84+
// accessed asynchronously after framework cleanup. Kitex is gradually removing
85+
// this pooling mechanism; this function is kept only for compatibility during
86+
// the migration.
8287
func NewRPCInfoWithInlineFields() RPCInfo {
8388
return inlineRPCInfoPool.Get().(*inlineRPCInfo)
8489
}

‎pkg/rpcinfo/rpcstats.go‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -33,10 +33,13 @@ var (
3333
_ internal.Reusable = (*event)(nil)
3434

3535
// Deprecated: rpcStats pooling is part of the legacy RPCInfo pooling
36-
// mechanism. When RPCInfo pooling is disabled, framework-owned rpcStats
37-
// objects are no longer put back through the RPCInfo lifecycle.
36+
// mechanism under migration. RPCInfo pooling may cause panic or data races
37+
// when RPCInfo is accessed asynchronously after framework cleanup. Kitex is
38+
// gradually removing this pooling mechanism.
3839
rpcStatsPool = sync.Pool{New: func() interface{} { return newRPCStats() }}
3940

41+
// Deprecated: event pooling is part of rpcinfo's legacy pooling internals
42+
// and is kept only for compatibility during the RPCInfo pooling migration.
4043
eventPool = sync.Pool{New: func() interface{} { return &event{} }}
4144

4245
once sync.Once
@@ -87,7 +90,7 @@ func (e *event) zero() {
8790
// Recycle reuses the event.
8891
//
8992
// Deprecated: event recycling is part of rpcinfo's legacy pooling internals and
90-
// will be removed as Kitex migrates away from RPCInfo pooling.
93+
// is kept only for compatibility during the RPCInfo pooling migration.
9194
func (e *event) Recycle() {
9295
e.zero()
9396
eventPool.Put(e)
@@ -322,10 +325,11 @@ func (r *rpcStats) ImmutableView() RPCStats {
322325

323326
// Recycle reuses the rpcStats.
324327
//
325-
// Deprecated: rpcStats recycling is part of the RPCInfo pooling mechanism,
326-
// which may cause panic when RPCInfo is accessed asynchronously after it has
327-
// been recycled. Kitex is gradually migrating away from RPCInfo pooling and will
328-
// remove this pooling mechanism in the future.
328+
// Deprecated: rpcStats recycling is part of the legacy RPCInfo pooling
329+
// mechanism under migration. It may cause panic or data races when RPCInfo is
330+
// accessed asynchronously after framework cleanup. Kitex is gradually removing
331+
// this pooling mechanism; this method is kept only for compatibility during the
332+
// migration.
329333
func (r *rpcStats) Recycle() {
330334
r.Reset()
331335
rpcStatsPool.Put(r)

0 commit comments

Comments
 (0)