_ 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          * Destroys the object, freeing associated resources. After this call, any access
  39          * to this object may result in a SEGFAULT or worse.
  40          *
  41          * You should generally NEVER call this method. You should let the garbage collector
  42          * do this for you when it finalizes objects. However, it may be useful for types
  43          * which represent locks and should be closed immediately to avoid holding locks
  44          * until the GC runs.
  45          */
  46         public void destroy() {
  47                 if (ptr != 0) { bindings.SocketDescriptor_free(ptr); }
  48                 ptr = 0;
  49         }
  50         public static interface SocketDescriptorInterface {
  51                 /**
  52                  * Attempts to send some data from the given slice to the peer.
  53                  *
  54                  * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
  55                  * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
  56                  * called and further write attempts may occur until that time.
  57                  *
  58                  * If the returned size is smaller than `data.len()`, a
  59                  * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
  60                  * written. Additionally, until a `send_data` event completes fully, no further
  61                  * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
  62                  * prevent denial-of-service issues, you should not read or buffer any data from the socket
  63                  * until then.
  64                  *
  65                  * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
  66                  * (indicating that read events should be paused to prevent DoS in the send buffer),
  67                  * `resume_read` may be set indicating that read events on this descriptor should resume. A
  68                  * `resume_read` of false carries no meaning, and should not cause any action.
  69                  */
  70                 long send_data(byte[] data, boolean resume_read);
  71                 /**
  72                  * Disconnect the socket pointed to by this SocketDescriptor.
  73                  *
  74                  * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
  75                  * call (doing so is a noop).
  76                  */
  77                 void disconnect_socket();
  78                 /**
  79                  * Checks if two objects are equal given this object's this_arg pointer and another object.
  80                  */
  81                 boolean eq(SocketDescriptor other_arg);
  82                 /**
  83                  * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer.
  84                  * This is used, for example, for inclusion of this object in a hash map.
  85                  */
  86                 long hash();
  87         }
  88         private static class LDKSocketDescriptorHolder { SocketDescriptor held; }
  89         public static SocketDescriptor new_impl(SocketDescriptorInterface arg) {
  90                 final LDKSocketDescriptorHolder impl_holder = new LDKSocketDescriptorHolder();
  91                 impl_holder.held = new SocketDescriptor(new bindings.LDKSocketDescriptor() {
  92                         @Override public long send_data(byte[] data, boolean resume_read) {
  93                                 long ret = arg.send_data(data, resume_read);
  94                                 Reference.reachabilityFence(arg);
  95                                 return ret;
  96                         }
  97                         @Override public void disconnect_socket() {
  98                                 arg.disconnect_socket();
  99                                 Reference.reachabilityFence(arg);
 100                         }
 101                         @Override public boolean eq(long other_arg) {
 102                                 SocketDescriptor ret_hu_conv = new SocketDescriptor(null, other_arg);
 103                                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 104                                 boolean ret = arg.eq(ret_hu_conv);
 105                                 Reference.reachabilityFence(arg);
 106                                 return ret;
 107                         }
 108                         @Override public long hash() {
 109                                 long ret = arg.hash();
 110                                 Reference.reachabilityFence(arg);
 111                                 return ret;
 112                         }
 113                 });
 114                 return impl_holder.held;
 115         }
 116         /**
 117          * Attempts to send some data from the given slice to the peer.
 118          *
 119          * Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
 120          * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
 121          * called and further write attempts may occur until that time.
 122          *
 123          * If the returned size is smaller than `data.len()`, a
 124          * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
 125          * written. Additionally, until a `send_data` event completes fully, no further
 126          * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
 127          * prevent denial-of-service issues, you should not read or buffer any data from the socket
 128          * until then.
 129          *
 130          * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
 131          * (indicating that read events should be paused to prevent DoS in the send buffer),
 132          * `resume_read` may be set indicating that read events on this descriptor should resume. A
 133          * `resume_read` of false carries no meaning, and should not cause any action.
 134          */
 135         public long send_data(byte[] data, boolean resume_read) {
 136                 long ret = bindings.SocketDescriptor_send_data(this.ptr, data, resume_read);
 137                 Reference.reachabilityFence(this);
 138                 Reference.reachabilityFence(data);
 139                 Reference.reachabilityFence(resume_read);
 140                 return ret;
 141         }
 142
 143         /**
 144          * Disconnect the socket pointed to by this SocketDescriptor.
 145          *
 146          * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
 147          * call (doing so is a noop).
 148          */
 149         public void disconnect_socket() {
 150                 bindings.SocketDescriptor_disconnect_socket(this.ptr);
 151                 Reference.reachabilityFence(this);
 152         }
 153
 154         /**
 155          * Calculate a succinct non-cryptographic hash for an object given its this_arg pointer.
 156          * This is used, for example, for inclusion of this object in a hash map.
 157          */
 158         public long hash() {
 159                 long ret = bindings.SocketDescriptor_hash(this.ptr);
 160                 Reference.reachabilityFence(this);
 161                 return ret;
 162         }
 163
 164         @Override public int hashCode() {
 165                 return (int)this.hash();
 166         }
 167         long clone_ptr() {
 168                 long ret = bindings.SocketDescriptor_clone_ptr(this.ptr);
 169                 Reference.reachabilityFence(this);
 170                 return ret;
 171         }
 172
 173         /**
 174          * Creates a copy of a SocketDescriptor
 175          */
 176         public SocketDescriptor clone() {
 177                 long ret = bindings.SocketDescriptor_clone(this.ptr);
 178                 Reference.reachabilityFence(this);
 179                 if (ret >= 0 && ret <= 4096) { return null; }
 180                 SocketDescriptor ret_hu_conv = new SocketDescriptor(null, ret);
 181                 if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
 182                 return ret_hu_conv;
 183         }
 184
 185 }