readpref.go

Documentation: go.mongodb.org/mongo-driver/mongo/readpref

     1  // Copyright (C) MongoDB, Inc. 2017-present.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License"); you may
     4  // not use this file except in compliance with the License. You may obtain
     5  // a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
     6  
     7  // Package readpref defines read preferences for MongoDB queries.
     8  package readpref // import "go.mongodb.org/mongo-driver/mongo/readpref"
     9  
    10  import (
    11  	"bytes"
    12  	"errors"
    13  	"fmt"
    14  	"time"
    15  
    16  	"go.mongodb.org/mongo-driver/tag"
    17  )
    18  
    19  var (
    20  	errInvalidReadPreference = errors.New("can not specify tags, max staleness, or hedge with mode primary")
    21  )
    22  
    23  // Primary constructs a read preference with a PrimaryMode.
    24  func Primary() *ReadPref {
    25  	return &ReadPref{mode: PrimaryMode}
    26  }
    27  
    28  // PrimaryPreferred constructs a read preference with a PrimaryPreferredMode.
    29  func PrimaryPreferred(opts ...Option) *ReadPref {
    30  	// New only returns an error with a mode of Primary
    31  	rp, _ := New(PrimaryPreferredMode, opts...)
    32  	return rp
    33  }
    34  
    35  // SecondaryPreferred constructs a read preference with a SecondaryPreferredMode.
    36  func SecondaryPreferred(opts ...Option) *ReadPref {
    37  	// New only returns an error with a mode of Primary
    38  	rp, _ := New(SecondaryPreferredMode, opts...)
    39  	return rp
    40  }
    41  
    42  // Secondary constructs a read preference with a SecondaryMode.
    43  func Secondary(opts ...Option) *ReadPref {
    44  	// New only returns an error with a mode of Primary
    45  	rp, _ := New(SecondaryMode, opts...)
    46  	return rp
    47  }
    48  
    49  // Nearest constructs a read preference with a NearestMode.
    50  func Nearest(opts ...Option) *ReadPref {
    51  	// New only returns an error with a mode of Primary
    52  	rp, _ := New(NearestMode, opts...)
    53  	return rp
    54  }
    55  
    56  // New creates a new ReadPref.
    57  func New(mode Mode, opts ...Option) (*ReadPref, error) {
    58  	rp := &ReadPref{
    59  		mode: mode,
    60  	}
    61  
    62  	if mode == PrimaryMode && len(opts) != 0 {
    63  		return nil, errInvalidReadPreference
    64  	}
    65  
    66  	for _, opt := range opts {
    67  		if opt == nil {
    68  			continue
    69  		}
    70  		err := opt(rp)
    71  		if err != nil {
    72  			return nil, err
    73  		}
    74  	}
    75  
    76  	return rp, nil
    77  }
    78  
    79  // ReadPref determines which servers are considered suitable for read operations.
    80  type ReadPref struct {
    81  	maxStaleness    time.Duration
    82  	maxStalenessSet bool
    83  	mode            Mode
    84  	tagSets         []tag.Set
    85  	hedgeEnabled    *bool
    86  }
    87  
    88  // MaxStaleness is the maximum amount of time to allow
    89  // a server to be considered eligible for selection. The
    90  // second return value indicates if this value has been set.
    91  func (r *ReadPref) MaxStaleness() (time.Duration, bool) {
    92  	return r.maxStaleness, r.maxStalenessSet
    93  }
    94  
    95  // Mode indicates the mode of the read preference.
    96  func (r *ReadPref) Mode() Mode {
    97  	return r.mode
    98  }
    99  
   100  // TagSets are multiple tag sets indicating
   101  // which servers should be considered.
   102  func (r *ReadPref) TagSets() []tag.Set {
   103  	return r.tagSets
   104  }
   105  
   106  // HedgeEnabled returns whether or not hedged reads are enabled for this read preference. If this option was not
   107  // specified during read preference construction, nil is returned.
   108  func (r *ReadPref) HedgeEnabled() *bool {
   109  	return r.hedgeEnabled
   110  }
   111  
   112  // String returns a human-readable description of the read preference.
   113  func (r *ReadPref) String() string {
   114  	var b bytes.Buffer
   115  	b.WriteString(r.mode.String())
   116  	delim := "("
   117  	if r.maxStalenessSet {
   118  		fmt.Fprintf(&b, "%smaxStaleness=%v", delim, r.maxStaleness)
   119  		delim = " "
   120  	}
   121  	for _, tagSet := range r.tagSets {
   122  		fmt.Fprintf(&b, "%stagSet=%s", delim, tagSet.String())
   123  		delim = " "
   124  	}
   125  	if r.hedgeEnabled != nil {
   126  		fmt.Fprintf(&b, "%shedgeEnabled=%v", delim, *r.hedgeEnabled)
   127  		delim = " "
   128  	}
   129  	if delim != "(" {
   130  		b.WriteString(")")
   131  	}
   132  	return b.String()
   133  }
   134
View as plain text