setu.rst (6065B)
1 2 .. index:: 3 double: SETU; subsystem 4 5 .. _SETU-Subsystem-Dev: 6 7 SETU 8 ==== 9 10 .. _Union-Set-API: 11 12 Union Set API 13 ^^^^^^^^^^^^^ 14 15 New sets are created with ``GNUNET_SETU_create``. Only the local peer's 16 configuration (as each set has its own client connection) must be 17 provided. The set exists until either the client calls 18 ``GNUNET_SETU_destroy`` or the client's connection to the service is 19 disrupted. In the latter case, the client is notified by the return 20 value of functions dealing with sets. This return value must always be 21 checked. 22 23 Elements are added with ``GNUNET_SETU_add_element``. 24 25 .. _Union-Listeners: 26 27 Union Listeners 28 ^^^^^^^^^^^^^^^ 29 30 Listeners are created with ``GNUNET_SETU_listen``. Each time time a 31 remote peer suggests a set operation with an application id and 32 operation type matching a listener, the listener's callback is invoked. 33 The client then must synchronously call either ``GNUNET_SETU_accept`` or 34 ``GNUNET_SETU_reject``. Note that the operation will not be started 35 until the client calls ``GNUNET_SETU_commit`` (see Section \"Supplying a 36 Set\"). 37 38 .. _Union-Operations: 39 40 Union Operations 41 ^^^^^^^^^^^^^^^^ 42 43 Operations to be initiated by the local peer are created with 44 ``GNUNET_SETU_prepare``. Note that the operation will not be started 45 until the client calls ``GNUNET_SETU_commit`` (see Section \"Supplying a 46 Set\"). 47 48 .. _Supplying-a-Set-for-Union: 49 50 Supplying a Set for Union 51 ^^^^^^^^^^^^^^^^^^^^^^^^^ 52 53 To create symmetry between the two ways of starting a set operation 54 (accepting and initiating it), the operation handles returned by 55 ``GNUNET_SETU_accept`` and ``GNUNET_SETU_prepare`` do not yet have a set 56 to operate on, thus they can not do any work yet. 57 58 The client must call ``GNUNET_SETU_commit`` to specify a set to use for 59 an operation. ``GNUNET_SETU_commit`` may only be called once per set 60 operation. 61 62 .. _The-Union-Result-Callback: 63 64 The Union Result Callback 65 ^^^^^^^^^^^^^^^^^^^^^^^^^ 66 67 Clients must specify both a result mode and a result callback with 68 ``GNUNET_SETU_accept`` and ``GNUNET_SETU_prepare``. The result callback 69 with a status indicating either that an element was received, 70 transmitted to the other peer (if this information was requested), or if 71 the operation failed or ultimately succeeded. 72 73 .. _The-SETU-Client_002dService-Protocol: 74 75 The SETU Client-Service Protocol 76 -------------------------------- 77 78 .. _Creating-Union-Sets: 79 80 Creating Union Sets 81 ^^^^^^^^^^^^^^^^^^^ 82 83 For each set of a client, there exists a client connection to the 84 service. Sets are created by sending the ``GNUNET_SERVICE_SETU_CREATE`` 85 message over a new client connection. Multiple operations for one set 86 are multiplexed over one client connection, using a request id supplied 87 by the client. 88 89 .. _Listeners-for-Union: 90 91 Listeners for Union 92 ^^^^^^^^^^^^^^^^^^^ 93 94 Each listener also requires a separate client connection. By sending the 95 ``GNUNET_SERVICE_SETU_LISTEN`` message, the client notifies the service 96 of the application id and operation type it is interested in. A client 97 rejects an incoming request by sending ``GNUNET_SERVICE_SETU_REJECT`` on 98 the listener's client connection. In contrast, when accepting an 99 incoming request, a ``GNUNET_SERVICE_SETU_ACCEPT`` message must be sent 100 over the set that is supplied for the set operation. 101 102 .. _Initiating-Union-Operations: 103 104 Initiating Union Operations 105 ^^^^^^^^^^^^^^^^^^^^^^^^^^^ 106 107 Operations with remote peers are initiated by sending a 108 ``GNUNET_SERVICE_SETU_EVALUATE`` message to the service. The client 109 connection that this message is sent by determines the set to use. 110 111 .. _Modifying-Union-Sets: 112 113 Modifying Union Sets 114 ^^^^^^^^^^^^^^^^^^^^ 115 116 Sets are modified with the ``GNUNET_SERVICE_SETU_ADD`` message. 117 118 .. _Union-Results-and-Operation-Status: 119 120 Union Results and Operation Status 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 122 123 The service notifies the client of result elements and success/failure 124 of a set operation with the ``GNUNET_SERVICE_SETU_RESULT`` message. 125 126 .. _The-SETU-Union-Peer_002dto_002dPeer-Protocol: 127 128 The SETU Union Peer-to-Peer Protocol 129 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 130 131 The SET union protocol is based on Eppstein's efficient set 132 reconciliation without prior context. You should read this paper first 133 if you want to understand the protocol. 134 135 .. todo:: Link to Eppstein's paper! 136 137 The union protocol operates over CADET and starts with a 138 GNUNET_MESSAGE_TYPE_SETU_P2P_OPERATION_REQUEST being sent by the peer 139 initiating the operation to the peer listening for inbound requests. It 140 includes the number of elements of the initiating peer, which is 141 currently not used. 142 143 The listening peer checks if the operation type and application 144 identifier are acceptable for its current state. If not, it responds 145 with a ``GNUNET_MESSAGE_TYPE_SETU_RESULT`` and a status of 146 ``GNUNET_SETU_STATUS_FAILURE`` (and terminates the CADET channel). 147 148 If the application accepts the request, it sends back a strata estimator 149 using a message of type GNUNET_MESSAGE_TYPE_SETU_P2P_SE. The initiator 150 evaluates the strata estimator and initiates the exchange of invertible 151 Bloom filters, sending a GNUNET_MESSAGE_TYPE_SETU_P2P_IBF. 152 153 During the IBF exchange, if the receiver cannot invert the Bloom filter 154 or detects a cycle, it sends a larger IBF in response (up to a defined 155 maximum limit; if that limit is reached, the operation fails). Elements 156 decoded while processing the IBF are transmitted to the other peer using 157 GNUNET_MESSAGE_TYPE_SETU_P2P_ELEMENTS, or requested from the other peer 158 using GNUNET_MESSAGE_TYPE_SETU_P2P_ELEMENT_REQUESTS messages, depending 159 on the sign observed during decoding of the IBF. Peers respond to a 160 GNUNET_MESSAGE_TYPE_SETU_P2P_ELEMENT_REQUESTS message with the 161 respective element in a GNUNET_MESSAGE_TYPE_SETU_P2P_ELEMENTS message. 162 If the IBF fully decodes, the peer responds with a 163 GNUNET_MESSAGE_TYPE_SETU_P2P_DONE message instead of another 164 GNUNET_MESSAGE_TYPE_SETU_P2P_IBF. 165 166 All Bloom filter operations use a salt to mingle keys before hashing 167 them into buckets, such that future iterations have a fresh chance of 168 succeeding if they failed due to collisions before.