_ Git - ldk-java/blob - src/main/java/org/ldk/structs/SocketDescriptor.java

   1 package org.ldk.structs;
   2
   3 import org.ldk.impl.bindings;
   4 import org.ldk.enums.*;
   5 import org.ldk.util.*;
   6 import java.util.Arrays;
   7 import java.lang.ref.Reference;
   8 import javax.annotation.Nullable;
   9
  10 /**
  11  * Provides an object which can be used to send data to and which uniquely identifies a connection
  12  * to a remote host. You will need to be able to generate multiple of these which meet Eq and
  13  * implement Hash to meet the PeerManager API.
  14  *
  15  * For efficiency, Clone should be relatively cheap for this type.
  16  *
  17  * Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original
  18  * has been disconnected, the [`PeerManager`] has been informed of the disconnection (either by it
  19  * having triggered the disconnection or a call to [`PeerManager::socket_disconnected`]), and no
  20  * further calls to the [`PeerManager`] related to the original socket occur. This allows you to
  21  * use a file descriptor for your SocketDescriptor directly, however for simplicity you may wish
  22  * to simply use another value which is guaranteed to be globally unique instead.
  23  */
  24 @SuppressWarnings("unchecked") // We correctly assign various generic arrays
  25 public class SocketDescriptor extends CommonBase {
  26         final bindings.LDKSocketDescriptor bindings_instance;
  27         SocketDescriptor(Object _dummy, long ptr) { super(ptr); bindings_instance = null; }
  28         private SocketDescriptor(bindings.LDKSocketDescriptor arg) {
  29                 super(bindings.LDKSocketDescriptor_new(arg));
  30                 this.ptrs_to.add(arg);
  31                 this.bindings_instance = arg;
  32         }
  33         @Override @SuppressWarnings("deprecation")
  34         protected void finalize() throws Throwable {
  35                 if (ptr != 0) { bindings.SocketDescriptor_free(ptr); } super.finalize();
  36         }
  37
  38         public static interface SocketDescriptorInterface {
  39                 /**
  40                  * Attempts to send some data from the given slice to the peer.
  41                  *
  42                  * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
  43                  * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
  44                  * called and further write attempts may occur until that time.
  45                  *
  46                  * If the returned size is smaller than `data.len()`, a
  47                  * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
  48                  * written. Additionally, until a `send_data` event completes fully, no further
  49                  * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
  50                  * prevent denial-of-service issues, you should not read or buffer any data from the socket
  51                  * until then.
  52                  *
  53                  * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
  54                  * (indicating that read events should be paused to prevent DoS in the send buffer),
  55                  * `resume_read` may be set indicating that read events on this descriptor should resume. A
  56                  * `resume_read` of false carries no meaning, and should not cause any action.
  57                  */
  58                 long send_data(byte[] data, boolean resume_read);
  59                 /**
  60                  * Disconnect the socket pointed to by this SocketDescriptor.
  61                  *
  62                  * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
  63                  * call (doing so is a noop).
  64                  */
  65                 void disconnect_socket();
  66                 /**
  67                  * Checks if two objects are equal given this object's this_arg pointer and another object.
  68                  */
  69                 boolean eq(SocketDescriptor other_arg);
  70                 /**
  71                  * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer.
  72                  * This is used, for example, for inclusion of this object in a hash map.
  73                  */
  74                 long hash();
  75         }
  76         private static class LDKSocketDescriptorHolder { SocketDescriptor held; }
  77         public static SocketDescriptor new_impl(SocketDescriptorInterface arg) {
  78                 final LDKSocketDescriptorHolder impl_holder = new LDKSocketDescriptorHolder();
  79                 impl_holder.held = new SocketDescriptor(new bindings.LDKSocketDescriptor() {
  80                         @Override public long send_data(byte[] data, boolean resume_read) {
  81                                 long ret = arg.send_data(data, resume_read);
  82                                 return ret;
  83                         }
  84                         @Override public void disconnect_socket() {
  85                                 arg.disconnect_socket();
  86                         }
  87                         @Override public boolean eq(long other_arg) {
  88                                 SocketDescriptor ret_hu_conv = new SocketDescriptor(null, other_arg);
  89                                 ret_hu_conv.ptrs_to.add(this);
  90                                 boolean ret = arg.eq(ret_hu_conv);
  91                                 return ret;
  92                         }
  93                         @Override public long hash() {
  94                                 long ret = arg.hash();
  95                                 return ret;
  96                         }
  97                 });
  98                 return impl_holder.held;
  99         }
 100         /**
 101          * Attempts to send some data from the given slice to the peer.
 102          *
 103          * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
 104          * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
 105          * called and further write attempts may occur until that time.
 106          *
 107          * If the returned size is smaller than `data.len()`, a
 108          * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
 109          * written. Additionally, until a `send_data` event completes fully, no further
 110          * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
 111          * prevent denial-of-service issues, you should not read or buffer any data from the socket
 112          * until then.
 113          *
 114          * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
 115          * (indicating that read events should be paused to prevent DoS in the send buffer),
 116          * `resume_read` may be set indicating that read events on this descriptor should resume. A
 117          * `resume_read` of false carries no meaning, and should not cause any action.
 118          */
 119         public long send_data(byte[] data, boolean resume_read) {
 120                 long ret = bindings.SocketDescriptor_send_data(this.ptr, data, resume_read);
 121                 Reference.reachabilityFence(this);
 122                 Reference.reachabilityFence(data);
 123                 Reference.reachabilityFence(resume_read);
 124                 return ret;
 125         }
 126
 127         /**
 128          * Disconnect the socket pointed to by this SocketDescriptor.
 129          *
 130          * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
 131          * call (doing so is a noop).
 132          */
 133         public void disconnect_socket() {
 134                 bindings.SocketDescriptor_disconnect_socket(this.ptr);
 135                 Reference.reachabilityFence(this);
 136         }
 137
 138         /**
 139          * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer.
 140          * This is used, for example, for inclusion of this object in a hash map.
 141          */
 142         public long hash() {
 143                 long ret = bindings.SocketDescriptor_hash(this.ptr);
 144                 Reference.reachabilityFence(this);
 145                 return ret;
 146         }
 147
 148         @Override public int hashCode() {
 149                 return (int)this.hash();
 150         }
 151         long clone_ptr() {
 152                 long ret = bindings.SocketDescriptor_clone_ptr(this.ptr);
 153                 Reference.reachabilityFence(this);
 154                 return ret;
 155         }
 156
 157         /**
 158          * Creates a copy of a SocketDescriptor
 159          */
 160         public SocketDescriptor clone() {
 161                 long ret = bindings.SocketDescriptor_clone(this.ptr);
 162                 Reference.reachabilityFence(this);
 163                 if (ret >= 0 && ret <= 4096) { return null; }
 164                 SocketDescriptor ret_hu_conv = new SocketDescriptor(null, ret);
 165                 ret_hu_conv.ptrs_to.add(this);
 166                 return ret_hu_conv;
 167         }
 168
 169 }