github.com/keltia/go-ipfs@v0.3.8-0.20150909044612-210793031c63/exchange/bitswap/README.md (about)

     1  # Bitswap
     2  
     3  ## Protocol
     4  Bitswap is the data trading module for ipfs, it manages requesting and sending
     5  blocks to and from other peers in the network. Bitswap has two main jobs, the
     6  first is to acquire blocks requested by the client from the network. The second
     7  is to judiciously send blocks in its posession to other peers who want them.
     8  
     9  Bitswap is a message based protocol, as opposed to response-reply. All messages
    10  contain wantlists, or blocks. Upon receiving a wantlist, a node should consider
    11  sending out wanted blocks if they have them. Upon receiving blocks, the node
    12  should send out a notification called a 'Cancel' signifying that they no longer
    13  want the block. At a protocol level, bitswap is very simple.
    14  
    15  ## go-ipfs Implementation
    16  Internally, when a message with a wantlist is received, it is sent to the
    17  decision engine to be considered, and blocks that we have that are wanted are
    18  placed into the peer request queue. Any block we possess that is wanted by
    19  another peer has a task in the peer request queue created for it. The peer
    20  request queue is a priority queue that sorts available tasks by some metric,
    21  currently, that metric is very simple and aims to fairly address the tasks
    22  of each other peer. More advanced decision logic will be implemented in the
    23  future. Task workers pull tasks to be done off of the queue, retreive the block
    24  to be sent, and send it off. The number of task workers is limited by a constant
    25  factor.
    26  
    27  Client requests for new blocks are handled by the want manager, for every new
    28  block (or set of blocks) wanted, the 'WantBlocks' method is invoked. The want
    29  manager then ensures that connected peers are notified of the new block that we
    30  want by sending the new entries to a message queue for each peer. The message
    31  queue will loop while there is work available and do the following: 1) Ensure it
    32  has a connection to its peer, 2) grab the message to be sent, and 3) send it.
    33  If new messages are added while the loop is in steps 1 or 3, the messages are
    34  combined into one to avoid having to keep an actual queue and send multiple
    35  messages. The same process occurs when the client receives a block and sends a
    36  cancel message for it.
    37