dubbo.apache.org/dubbo-go/v3@v3.1.1/cluster/router/router.go (about)

     1  /*
     2   * Licensed to the Apache Software Foundation (ASF) under one or more
     3   * contributor license agreements.  See the NOTICE file distributed with
     4   * this work for additional information regarding copyright ownership.
     5   * The ASF licenses this file to You under the Apache License, Version 2.0
     6   * (the "License"); you may not use this file except in compliance with
     7   * the License.  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  package router
    19  
    20  import (
    21  	"github.com/RoaringBitmap/roaring"
    22  )
    23  
    24  import (
    25  	"dubbo.apache.org/dubbo-go/v3/common"
    26  	"dubbo.apache.org/dubbo-go/v3/protocol"
    27  )
    28  
    29  // PriorityRouterFactory creates priority router with url
    30  type PriorityRouterFactory interface {
    31  	// NewPriorityRouter creates router instance with URL
    32  	NewPriorityRouter() (PriorityRouter, error)
    33  }
    34  
    35  // PriorityRouter routes with priority
    36  type PriorityRouter interface {
    37  	// Route Determine the target invokers list.
    38  	Route([]protocol.Invoker, *common.URL, protocol.Invocation) []protocol.Invoker
    39  
    40  	// URL Return URL in router
    41  	URL() *common.URL
    42  
    43  	// Priority Return Priority in router
    44  	// 0 to ^int(0) is better
    45  	Priority() int64
    46  
    47  	// Notify the router the invoker list
    48  	Notify(invokers []protocol.Invoker)
    49  }
    50  
    51  // Poolable caches address pool and address metadata for a router instance which will be used later in Router's Route.
    52  type Poolable interface {
    53  	// Pool created address pool and address metadata from the invokers.
    54  	Pool([]protocol.Invoker) (AddrPool, AddrMetadata)
    55  
    56  	// ShouldPool returns if it should pool. One typical scenario is a router rule changes, in this case, a pooling
    57  	// is necessary, even if the addresses not changed at all.
    58  	ShouldPool() bool
    59  
    60  	// Name return the Poolable's name.
    61  	Name() string
    62  }
    63  
    64  // AddrPool is an address pool, backed by a snapshot of address list, divided into categories.
    65  type AddrPool map[string]*roaring.Bitmap
    66  
    67  // AddrMetadata is address metadata, collected from a snapshot of address list by a router, if it implements Poolable.
    68  type AddrMetadata interface {
    69  	// Source indicates where the metadata comes from.
    70  	Source() string
    71  }
    72  
    73  // Cache caches all addresses relevant info for a snapshot of received invokers. It keeps a snapshot of the received
    74  // address list, and also keeps address pools and address metadata from routers based on the same address snapshot, if
    75  // the router implements Poolable.
    76  type Cache interface {
    77  	// GetInvokers returns the snapshot of received invokers.
    78  	GetInvokers() []protocol.Invoker
    79  
    80  	// FindAddrPool returns address pool associated with the given Poolable instance.
    81  	FindAddrPool(Poolable) AddrPool
    82  
    83  	// FindAddrMeta returns address metadata associated with the given Poolable instance.
    84  	FindAddrMeta(Poolable) AddrMetadata
    85  }