google.golang.org/grpc@v1.72.2/experimental/experimental.go (about)

     1  /*
     2   *
     3   * Copyright 2023 gRPC authors.
     4   *
     5   * Licensed under the Apache License, Version 2.0 (the "License");
     6   * you may not use this file except in compliance with the License.
     7   * You may obtain a copy of the License at
     8   *
     9   *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   *
    17   */
    18  
    19  // Package experimental is a collection of experimental features that might
    20  // have some rough edges to them. Housing experimental features in this package
    21  // results in a user accessing these APIs as `experimental.Foo`, thereby making
    22  // it explicit that the feature is experimental and using them in production
    23  // code is at their own risk.
    24  //
    25  // All APIs in this package are experimental.
    26  package experimental
    27  
    28  import (
    29  	"google.golang.org/grpc"
    30  	"google.golang.org/grpc/internal"
    31  	"google.golang.org/grpc/mem"
    32  )
    33  
    34  // WithBufferPool returns a grpc.DialOption that configures the use of bufferPool
    35  // for parsing incoming messages on a grpc.ClientConn, and for temporary buffers
    36  // when marshaling outgoing messages. By default, mem.DefaultBufferPool is used,
    37  // and this option only exists to provide alternative buffer pool implementations
    38  // to the client, such as more optimized size allocations etc. However, the
    39  // default buffer pool is already tuned to account for many different use-cases.
    40  //
    41  // Note: The following options will interfere with the buffer pool because they
    42  // require a fully materialized buffer instead of a sequence of buffers:
    43  // EnableTracing, and binary logging. In such cases, materializing the buffer
    44  // will generate a lot of garbage, reducing the overall benefit from using a
    45  // pool.
    46  func WithBufferPool(bufferPool mem.BufferPool) grpc.DialOption {
    47  	return internal.WithBufferPool.(func(mem.BufferPool) grpc.DialOption)(bufferPool)
    48  }
    49  
    50  // BufferPool returns a grpc.ServerOption that configures the server to use the
    51  // provided buffer pool for parsing incoming messages and for temporary buffers
    52  // when marshaling outgoing messages. By default, mem.DefaultBufferPool is used,
    53  // and this option only exists to provide alternative buffer pool implementations
    54  // to the server, such as more optimized size allocations etc. However, the
    55  // default buffer pool is already tuned to account for many different use-cases.
    56  //
    57  // Note: The following options will interfere with the buffer pool because they
    58  // require a fully materialized buffer instead of a sequence of buffers:
    59  // EnableTracing, and binary logging. In such cases, materializing the buffer
    60  // will generate a lot of garbage, reducing the overall benefit from using a
    61  // pool.
    62  func BufferPool(bufferPool mem.BufferPool) grpc.ServerOption {
    63  	return internal.BufferPool.(func(mem.BufferPool) grpc.ServerOption)(bufferPool)
    64  }