Fix hfp docs (#802)

* fix HFP docs to account for new behavior

* make comment stop rendering
This commit is contained in:
Jim Witschey
2017-07-19 14:28:56 -04:00
committed by GitHub
parent f42132ad45
commit fad8764b36
2 changed files with 14 additions and 5 deletions

View File

@@ -485,6 +485,10 @@ class HostFilterPolicy(LoadBalancingPolicy):
load_balancing_policy=blacklist_filter_policy, load_balancing_policy=blacklist_filter_policy,
) )
See the note in the :meth:`.make_query_plan` documentation for a caveat on
how wrapping ordering polices (e.g. :class:`.RoundRobinPolicy`) may break
desirable properties of the wrapped policy.
Please note that whitelist and blacklist policies are not recommended for Please note that whitelist and blacklist policies are not recommended for
general, day-to-day use. You probably want something like general, day-to-day use. You probably want something like
:class:`.DCAwareRoundRobinPolicy`, which prefers a local DC but has :class:`.DCAwareRoundRobinPolicy`, which prefers a local DC but has
@@ -546,10 +550,15 @@ class HostFilterPolicy(LoadBalancingPolicy):
def make_query_plan(self, working_keyspace=None, query=None): def make_query_plan(self, working_keyspace=None, query=None):
""" """
Defers to the child policy's Defers to the child policy's
:meth:`.LoadBalancingPolicy.make_query_plan`. Since host changes (up, :meth:`.LoadBalancingPolicy.make_query_plan` and filters the results.
down, addition, and removal) have not been propagated to the child
policy, the child policy will only ever return policies for which Note that this filtering may break desirable properties of the wrapped
:meth:`.predicate(host)` was truthy when that change occurred. policy in some cases. For instance, imagine if you configure this
policy to filter out ``host2``, and to wrap a round-robin policy that
rotates through three hosts in the order ``host1, host2, host3``,
``host2, host3, host1``, ``host3, host1, host2``, repeating. This
policy will yield ``host1, host3``, ``host3, host1``, ``host3, host1``,
disproportionately favoring ``host3``.
""" """
child_qp = self._child_policy.make_query_plan( child_qp = self._child_policy.make_query_plan(
working_keyspace=working_keyspace, query=query working_keyspace=working_keyspace, query=query

View File

@@ -26,7 +26,7 @@ Load Balancing
.. autoclass:: HostFilterPolicy .. autoclass:: HostFilterPolicy
# we document these methods manually so we can specify a param to predicate .. we document these methods manually so we can specify a param to predicate
.. automethod:: predicate(host) .. automethod:: predicate(host)
.. automethod:: distance .. automethod:: distance