Module Expr Str Import alias Import alias ImportFrom alias ImportFrom alias ImportFrom alias ImportFrom alias alias alias alias ImportFrom alias ImportFrom alias Assign NameStore Call NameLoad Str TupleLoad Str Str ClassDef bases NameLoad body Expr Str FunctionDef arguments args NameParam NameParam NameParam NameParam defaults NameLoad body Expr Call AttributeLoad NameLoad attr Str Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr Call NameLoad NameLoad Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr Call NameLoad NameLoad Assign AttributeStore NameLoad attr Dict Assign AttributeStore NameLoad attr Dict Assign AttributeStore NameLoad attr ListLoad Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr NameLoad Assign AttributeStore NameLoad attr NameLoad If CompareIs NameLoad NameLoad body Expr Call AttributeLoad NameLoad attr AttributeLoad NameLoad attr keyword AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr AttributeLoad NameLoad attr keyword AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Expr Call AttributeLoad NameLoad attr Str Assign NameStore AttributeLoad NameLoad attr Assign NameStore Call AttributeLoad NameLoad attr TryExcept body Assign NameStore Call AttributeLoad NameLoad attr Call AttributeLoad NameLoad attr NameLoad Assign NameStore Call AttributeLoad Str attr AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad NameLoad attr NameLoad handlers ExceptHandler type NameLoad body If CompareEq Call NameLoad Call AttributeLoad NameLoad attr NameLoad Num body Assign NameStore Str Expr Call AttributeLoad NameLoad attr keyword NameLoad orelse Assign NameStore Str Expr Call AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad AttributeLoad NameLoad attr attr Call NameLoad NameLoad NameLoad Return NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str If CompareEq AttributeLoad NameLoad attr AttributeLoad NameLoad attr body Return CompareGt BinOpSub Call AttributeLoad NameLoad attr Num AttributeLoad NameLoad attr orelse Return CompareGt BinOpSub Call AttributeLoad NameLoad attr Num AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Assign NameStore AttributeLoad NameLoad attr TryExcept body Delete SubscriptDel AttributeLoad NameLoad attr Index NameLoad Assign NameStore Call AttributeLoad Str attr NameLoad Expr Call AttributeLoad NameLoad attr NameLoad handlers ExceptHandler type NameLoad body TryExcept body Delete SubscriptDel AttributeLoad NameLoad attr Index NameLoad Assign NameStore Call AttributeLoad Str attr NameLoad Expr Call AttributeLoad NameLoad attr NameLoad handlers ExceptHandler type NameLoad body Assign NameStore Call AttributeLoad Str attr NameLoad Expr Call AttributeLoad NameLoad attr NameLoad Return Expr Call AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Assign NameStore Call AttributeLoad Str attr AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr NameLoad TryExcept body Delete SubscriptDel AttributeLoad NameLoad attr Index AttributeLoad NameLoad attr handlers ExceptHandler type NameLoad body Assign NameStore Call AttributeLoad Str attr AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr NameLoad Return Assign SubscriptStore AttributeLoad NameLoad attr Index AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam defaults NameLoad body Expr Str Assign NameStore Str AugAssignAdd NameStore Str Expr Call AttributeLoad NameLoad attr NameLoad If CompareIs NameLoad NameLoad body Assign AttributeStore NameLoad attr ListLoad For NameStore Call AttributeLoad AttributeLoad NameLoad attr attr body Expr Call AttributeLoad NameLoad attr For NameStore Call AttributeLoad AttributeLoad NameLoad attr attr body Expr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Assign NameStore ListComp NameLoad comprehension NameStore AttributeLoad NameLoad attr CompareEq Call NameLoad Call AttributeLoad NameLoad attr AttributeLoad NameLoad attr Num Expr Call AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body If CompareIs AttributeLoad NameLoad attr NameLoad body Assign NameStore Str AugAssignAdd NameStore Str Expr Call AttributeLoad NameLoad attr NameLoad Assign AttributeStore NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body For NameStore Call AttributeLoad AttributeLoad NameLoad attr attr body Expr Call AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam NameParam defaults AttributeLoad NameLoad attr NameLoad NameLoad body Assign NameStore Call NameLoad AttributeLoad NameLoad attr Assign NameStore Call NameLoad AttributeLoad NameLoad attr NameLoad AttributeLoad NameLoad attr AttributeLoad NameLoad attr NameLoad keyword NameLoad keyword NameLoad keyword NameLoad Assign SubscriptStore AttributeLoad NameLoad attr Index NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam NameParam NameParam defaults AttributeLoad NameLoad attr NameLoad NameLoad body For NameStore Call NameLoad NameLoad body Expr Call AttributeLoad NameLoad attr keyword NameLoad keyword NameLoad keyword NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults body For NameStore NameLoad body Expr Call AttributeLoad NameLoad attr keyword AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str For NameStore SubscriptLoad AttributeLoad NameLoad attr Slice body Assign NameStore AttributeLoad AttributeLoad NameLoad attr attr If Call AttributeLoad NameLoad attr NameLoad body Assign NameStore Call AttributeLoad Str attr AttributeLoad NameLoad attr Expr Call AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad AttributeLoad NameLoad attr attr NameLoad Expr Call AttributeLoad AttributeLoad NameLoad attr attr NameLoad decorator_list FunctionDef arguments args NameParam defaults body Expr Str If CompareLt Call AttributeLoad NameLoad attr AttributeLoad NameLoad attr body Assign NameStore Str Expr Call AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad NameLoad attr keyword AttributeLoad NameLoad attr If CompareLt Call AttributeLoad NameLoad attr AttributeLoad NameLoad attr body Assign NameStore Str Expr Call AttributeLoad NameLoad attr NameLoad Expr Call AttributeLoad NameLoad attr keyword AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad ListComp NameLoad comprehension NameStore Call AttributeLoad AttributeLoad NameLoad attr attr CompareEq AttributeLoad NameLoad attr AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad ListComp NameLoad comprehension NameStore Call AttributeLoad AttributeLoad NameLoad attr attr CompareEq AttributeLoad NameLoad attr AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad ListComp NameLoad comprehension NameStore Call AttributeLoad AttributeLoad NameLoad attr attr CompareEq AttributeLoad NameLoad attr AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad ListComp NameLoad comprehension NameStore Call AttributeLoad AttributeLoad NameLoad attr attr CompareEq AttributeLoad NameLoad attr AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return BinOpAdd Call AttributeLoad NameLoad attr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return BinOpAdd Call AttributeLoad NameLoad attr Call AttributeLoad NameLoad attr decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Return ListComp NameLoad comprehension NameStore Call AttributeLoad AttributeLoad NameLoad attr attr Call AttributeLoad NameLoad attr NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Return ListComp NameLoad comprehension NameStore Call AttributeLoad AttributeLoad NameLoad attr attr Call AttributeLoad NameLoad attr NameLoad decorator_list decorator_list
N/A N/A 
.. topic:: Details

    CircuitManager manages a pool of circuits. CircuitManager knows about all
    open and pending circuits and can make choices about how and when
    circuits are built and destroyed.

    Currently, it's up to CircuitManager to:

        - Create an initial pool of circuits (currently 4 IPv4 and 1 IPv6
          initial circuits by default)
        - Handle incoming requests for open circuits (made by streams) and
          assign suitable circuits to handle the requests
        - Decide when and if a circuit should be destroyed when its stream
          count drops to zero
        - Replenish the circuit pool when a circuit is destroyed and, if
          necessary, build new circuits to handle any (now orphaned) pending
          streams
        - Assign pending streams to newly opened circuits when the circuits
          complete their extension process
        - Destroy all open and pending circuits when oppy shuts down

 N/A logging N/A random collections namedtuple twisted.internet defer oppy.circuit.circuitbuildtask CircuitBuildTask oppy.circuit.definitions CircuitType DEFAULT_OPEN_IPv4 DEFAULT_OPEN_IPv6 MAX_STREAMS_V3 oppy.history.guards GuardManager oppy.util.tools ctr N/A PendingStream N/A namedtuple PendingStream N/A stream deferred CircuitManager N/A object N/A N/A Manage a pool of circuits. __init__ N/A N/A self connection_manager netstatus autobuild N/A True N/A N/A N/A N/A logging debug Creating circuit manager. N/A N/A self _netstatus netstatus N/A N/A self _guard_manager N/A GuardManager netstatus N/A N/A self _connection_manager connection_manager N/A N/A self _ctr N/A ctr MAX_STREAMS_V3 N/A N/A self _open_circuit_dict N/A N/A N/A self _circuit_build_task_dict N/A N/A N/A self _pending_stream_list N/A N/A N/A self _min_IPv4_count DEFAULT_OPEN_IPv4 N/A N/A self _min_IPv6_count DEFAULT_OPEN_IPv6 N/A N/A self _sent_open_message False N/A N/A autobuild True N/A N/A N/A N/A self _buildCircuits N/A self _min_IPv4_count circuit_type N/A CircuitType IPv4 N/A N/A N/A self _buildCircuits N/A self _min_IPv6_count circuit_type N/A CircuitType IPv6 N/A getOpenCircuit N/A N/A self stream N/A N/A N/A Return a deferred that will fire with an open circuit that can
        handle the stream's request.


        There are three general cases to handle when a new open circuit
        request comes in:

            1. An open circuit exists that can handle this request. In this
               case, choose a random circuit from the set of open circuits
               that can handle this request and immediately callback the
               deferred with the chosen open circuit.

            2. A pending circuit exists that, when open, can handle this
               request. In this case, add the request to a pool of pending
               requests. Whenever a circuit opens, circuit manager checks all
               pending requests and assigns any pending requests that the
               newly opened circuit can handle to that circuit. So when a
               pending circuit opens that can handle this stream, the
               stream's deferred will be called back with the fresly opened
               circuit.

            3. No open or pending circuits exist that can handle the request.
               In this case, begin building a new circuit that can. Add the
               request to a pending request pool and, when a circuit opens
               that can handle the request, callback this stream's deferred
               with the newly opened circuit.

        :param oppy.stream.stream.Stream stream: the stream that is
            requesting an open circuit
        :returns: **twisted.internet.defer.Deferred** which will fire when
            a circuit has opened that can handle this stream's request.
         N/A N/A N/A logging debug Circuit manager got an open circuit request. N/A request N/A stream request N/A d N/A N/A defer Deferred N/A N/A N/A c N/A N/A random choice N/A N/A self _getOpenCandidates request N/A msg N/A N/A Assigning request to circuit {}. format N/A c circuit_id N/A N/A N/A logging debug msg N/A N/A N/A d callback c N/A N/A N/A IndexError N/A N/A N/A N/A len N/A N/A self _getPendingCandidates request 0 N/A N/A msg Building a new circuit to handle request. N/A N/A N/A self _buildCircuit request request N/A N/A msg A CircuitBuildTask can eventually handle request. N/A N/A N/A logging debug msg N/A N/A N/A N/A self _pending_stream_list append N/A PendingStream stream d N/A d N/A shouldDestroyCircuit N/A N/A self circuit N/A N/A N/A Return **True** iff CircuitManager thinks the calling circuit
        should be destroyed.

        Circuits call shouldDestroyCircuit() when their number of open
        streams drops to zero. Since CircuitManager knows about all open
        and pending circuits, it can make an informed judgement about whether
        the calling circuit should be destroyed or remain open.

        Currently, CircuitManager maintains at least 4 open or pending IPv4
        circuits and one open or pending IPv6 circuit. If the number of
        streams on any circuit drops to zero and it can be closed while still
        satisfying these basic constraints, then CircuitManager tells it
        to begin destroying itself (returns True).

        :param oppy.circuit.circuit.Circuit circuit: circuit to
            consider destroying.
        :returns: **bool** **True** if CircuitManager decides this circuit
            should be destroyed, **False** otherwise.
         N/A N/A N/A circuit circuit_type N/A CircuitType IPv4 N/A N/A N/A N/A N/A N/A self _totalIPv4Count 1 N/A self _min_IPv4_count N/A N/A N/A N/A N/A N/A self _totalIPv6Count 1 N/A self _min_IPv6_count N/A circuitDestroyed N/A N/A self circuit N/A N/A N/A Circuits call circuitDestroyed() when they have cleaned up after
        themselves and closed.

        Circuits may need to do a number of things before references to
        them are completely removed. Exactly what steps a circuit needs to
        take before being fully destroyed depend on both the circuit's state
        and the state of the whole program. After a circuit has fully cleaned
        up after itself and taken all necessary closing actions, it calls
        CircuitManager.circuitDestroyed().

        circuitDestroyed() does three things:

            1. Remove the closed circuit from any internal maps.

            2. Check the pool of pending requests. If any pending requests
               exist that cannot be handled by any open or pending circuits,
               begin building a new circuit to handle these orphaned requests.
               This can happen when a circuit is built to handle a particular
               request but is then destroyed/an error occurs while it is being
               built.

            3. Check CircuitManager's basic open and pending circuit
               requirements to see if a new circuit of a certain type should
               be built. For instance, if an IPv4 circuit closes and the
               number of open and pending IPv4 circuits is below
               self._min_IPv4_count, a new IPv4 circuit will be built.

        :param circuit_id: id of circuit to be destroyed
        :type circuit_id: int
         N/A cid N/A circuit circuit_id N/A N/A N/A N/A N/A self _circuit_build_task_dict N/A cid N/A msg N/A N/A Destroyed CircuitBuildTask {}. format cid N/A N/A N/A logging debug msg N/A N/A N/A KeyError N/A N/A N/A N/A N/A N/A self _open_circuit_dict N/A cid N/A msg N/A N/A Destroyed open circuit {}. format cid N/A N/A N/A logging debug msg N/A N/A N/A KeyError N/A N/A msg N/A N/A Circuit manager was notified that circuit {} was destroyed, but manager has no reference to that circuit. format cid N/A N/A N/A logging debug msg N/A N/A N/A N/A self _assignAllPossiblePendingRequests N/A N/A N/A self _buildCircuitsForOrphanedPendingRequests N/A N/A N/A self _replenishCircuits N/A circuitOpened N/A N/A self circuit N/A N/A N/A Circuits call circuitOpened() when they have successfully
        completed their build process and are ready to handle incoming
        streams.

        When a circuit opens, CircuitManager:

            - removes it from the pending circuit map
            - adds it to the open circuit map
            - assigns any pending requests that this circuit can handle to
              this freshly opened circuit
            - if this is the first circuit successfully opened, send a nice
              message to the user letting them know oppy is ready to forward
              traffic

        :param oppy.circuit.circuit.Circuit circuit: circuit that
            has just opened.
         N/A msg N/A N/A Circuit manager notified that circuit {} opened. format N/A circuit circuit_id N/A N/A N/A logging debug msg N/A N/A N/A N/A N/A self _circuit_build_task_dict N/A N/A circuit circuit_id N/A N/A N/A KeyError N/A N/A msg N/A N/A Circuit manager has no reference to circuit {}. format N/A circuit circuit_id N/A N/A N/A logging debug msg N/A N/A N/A N/A self _open_circuit_dict N/A N/A circuit circuit_id circuit N/A N/A N/A self _assignPossiblePendingRequestsToCircuit circuit N/A N/A N/A self _notifyUserCircuitOpened N/A destroyAllCircuits N/A N/A self destroy_pending_streams N/A True N/A N/A Destroy all open and pending circuits **and** remove all pending
        requests.
         N/A msg Destroying all open and pending connections, circuits, and  N/A msg streams. N/A N/A N/A logging debug msg N/A N/A destroy_pending_streams True N/A N/A N/A self _pending_stream_list N/A N/A circuit N/A N/A N/A self _open_circuit_dict values N/A N/A N/A N/A circuit destroyCircuitFromManager N/A circuit N/A N/A N/A self _circuit_build_task_dict values N/A N/A N/A N/A circuit destroyCircuitFromManager N/A _buildCircuitsForOrphanedPendingRequests N/A N/A self N/A N/A N/A orphaned_streams N/A s N/A s N/A self _pending_stream_list N/A N/A len N/A N/A self _getPendingCandidates N/A s request 0 N/A N/A N/A self _buildCircuitsForPendingStreams orphaned_streams N/A _notifyUserCircuitOpened N/A N/A self N/A N/A N/A N/A N/A self _sent_open_message False N/A N/A msg Circuit built successfully! oppy is ready to forward  N/A msg traffic :) N/A N/A N/A logging info msg N/A N/A self _sent_open_message True N/A _assignAllPossiblePendingRequests N/A N/A self N/A N/A N/A circuit N/A N/A N/A self _open_circuit_dict values N/A N/A N/A N/A self _assignPossiblePendingRequestsToCircuit circuit N/A _buildCircuit N/A N/A self circuit_type request autobuild N/A N/A CircuitType IPv4 None True N/A N/A _id N/A next N/A self _ctr N/A task N/A CircuitBuildTask N/A self _connection_manager self N/A self _netstatus N/A self _guard_manager _id circuit_type circuit_type request request autobuild autobuild N/A N/A N/A self _circuit_build_task_dict N/A _id task N/A _buildCircuits N/A N/A self count circuit_type request autobuild N/A N/A CircuitType IPv4 None True N/A N/A _ N/A xrange count N/A N/A N/A N/A self _buildCircuit circuit_type circuit_type request request autobuild autobuild N/A _buildCircuitsForPendingStreams N/A N/A self pending_streams N/A N/A N/A p pending_streams N/A N/A N/A N/A self _buildCircuit request N/A p request N/A _assignPossiblePendingRequestsToCircuit N/A N/A self circuit N/A N/A N/A Check all pending requests and assign any requests to *circuit*
        that it can handle.

        If a pending request is assigned to *circuit*, remove that request
        from the pending request pool.

        :param oppy.circuit.circuit.Circuit circuit: circuit to try assigning
            pending requests to
         N/A pending_stream N/A N/A self _pending_stream_list N/A N/A N/A request N/A N/A pending_stream stream request N/A N/A N/A circuit canHandleRequest request N/A N/A msg N/A N/A Assigning pending request to opened circuit {}. format N/A circuit circuit_id N/A N/A N/A logging debug msg N/A N/A N/A N/A pending_stream deferred callback circuit N/A N/A N/A N/A self _pending_stream_list remove pending_stream N/A _replenishCircuits N/A N/A self N/A N/A N/A Decide whether or not to build a new circuit - called when a
        circuit is destroyed.

        Check CircuitManager's basic requirements for open/pending circuits.
        If they are not satisfied, build a new circuit.
         N/A N/A N/A N/A self _totalIPv4Count N/A self _min_IPv4_count N/A N/A msg Replenishing circuit pool with a new IPv4 circuit. N/A N/A N/A logging debug msg N/A N/A N/A self _buildCircuit circuit_type N/A CircuitType IPv4 N/A N/A N/A N/A self _totalIPv6Count N/A self _min_IPv6_count N/A N/A msg Replenishing circuit pool with a new IPv6 circuit. N/A N/A N/A logging debug msg N/A N/A N/A self _buildCircuit circuit_type N/A CircuitType IPv6 N/A _openIPv4Count N/A N/A self N/A N/A N/A Return the number of open IPv4 circuits.

        :returns: **int** number of open IPv4 circuits
         N/A N/A len N/A i N/A i N/A N/A N/A self _open_circuit_dict values N/A N/A i circuit_type N/A CircuitType IPv4 N/A _openIPv6Count N/A N/A self N/A N/A N/A Return the number of open IPv6 circuits.

        :returns: **int** number of open IPv6 circuits.
         N/A N/A len N/A i N/A i N/A N/A N/A self _open_circuit_dict values N/A N/A i circuit_type N/A CircuitType IPv6 N/A _pendingIPv4Count N/A N/A self N/A N/A N/A Return the number of pending IPv4 circuits.

        :returns: **int** number of pending IPv4 circuits.
         N/A N/A len N/A i N/A i N/A N/A N/A self _circuit_build_task_dict values N/A N/A i circuit_type N/A CircuitType IPv4 N/A _pendingIPv6Count N/A N/A self N/A N/A N/A Return the number of pending IPv6 circuits.

        :returns: **int** number of pending IPv6 circuits
         N/A N/A len N/A i N/A i N/A N/A N/A self _circuit_build_task_dict values N/A N/A i circuit_type N/A CircuitType IPv6 N/A _totalIPv4Count N/A N/A self N/A N/A N/A Return the total (open + pending) IPv4 circuits.

        :returns: **int** total IPv4 circuits
         N/A N/A N/A N/A self _openIPv4Count N/A N/A self _pendingIPv4Count N/A _totalIPv6Count N/A N/A self N/A N/A N/A Return the total (open + pending) IPv6 circuits.

        :returns: **int** total IPv6 circuits
         N/A N/A N/A N/A self _openIPv6Count N/A N/A self _pendingIPv6Count N/A _getOpenCandidates N/A N/A self request N/A N/A N/A Return a list of circuits whose exit relay claims to allow the
        *request*.

        :returns: **list, oppy.circuit.circuit.Circuit** open circuits whose
            exit relay can handle the request
         N/A N/A i N/A i N/A N/A N/A self _open_circuit_dict values N/A N/A i canHandleRequest request N/A _getPendingCandidates N/A N/A self request N/A N/A N/A Return a list of pending circuits that claim to handle the
        request.

        .. note:: Since a pending circuit may not yet have an exit relay,
            whether or not this circuit can *actually* handle the request
            is just an informed guess. It may turn out that it can't
            **actually** handle the request once the circuit is open.

        :returns: **list, oppy.circuit.circuit.Circuit** pending circuits
            that can (probably) handle the request
         N/A N/A i N/A i N/A N/A N/A self _circuit_build_task_dict values N/A N/A i canHandleRequest request N/A N/A