1 package org.ldk.structs;
3 import org.ldk.impl.bindings;
4 import org.ldk.enums.*;
6 import java.util.Arrays;
7 import java.lang.ref.Reference;
8 import javax.annotation.Nullable;
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.
15 * For efficiency, Clone should be relatively cheap for this type.
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.
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;
33 @Override @SuppressWarnings("deprecation")
34 protected void finalize() throws Throwable {
35 if (ptr != 0) { bindings.SocketDescriptor_free(ptr); } super.finalize();
38 * Destroys the object, freeing associated resources. After this call, any access
39 * to this object may result in a SEGFAULT or worse.
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
46 public void destroy() {
47 if (ptr != 0) { bindings.SocketDescriptor_free(ptr); }
50 public static interface SocketDescriptorInterface {
52 * Attempts to send some data from the given slice to the peer.
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.
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
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.
70 long send_data(byte[] data, boolean resume_read);
72 * Disconnect the socket pointed to by this SocketDescriptor.
74 * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
75 * call (doing so is a noop).
77 void disconnect_socket();
79 * Checks if two objects are equal given this object's this_arg pointer and another object.
81 boolean eq(SocketDescriptor other_arg);
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.
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);
97 @Override public void disconnect_socket() {
98 arg.disconnect_socket();
99 Reference.reachabilityFence(arg);
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);
108 @Override public long hash() {
109 long ret = arg.hash();
110 Reference.reachabilityFence(arg);
114 return impl_holder.held;
117 * Attempts to send some data from the given slice to the peer.
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.
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
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.
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);
144 * Disconnect the socket pointed to by this SocketDescriptor.
146 * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
147 * call (doing so is a noop).
149 public void disconnect_socket() {
150 bindings.SocketDescriptor_disconnect_socket(this.ptr);
151 Reference.reachabilityFence(this);
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.
159 long ret = bindings.SocketDescriptor_hash(this.ptr);
160 Reference.reachabilityFence(this);
164 @Override public int hashCode() {
165 return (int)this.hash();
168 long ret = bindings.SocketDescriptor_clone_ptr(this.ptr);
169 Reference.reachabilityFence(this);
174 * Creates a copy of a SocketDescriptor
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); };