import org.ldk.enums.*;
import org.ldk.util.*;
import java.util.Arrays;
+import java.lang.ref.Reference;
+import javax.annotation.Nullable;
/**
* Provides an object which can be used to send data to and which uniquely identifies a connection
* to a remote host. You will need to be able to generate multiple of these which meet Eq and
* implement Hash to meet the PeerManager API.
*
- * For efficiency, Clone should be relatively cheap for this type.
+ * For efficiency, [`Clone`] should be relatively cheap for this type.
*
- * You probably want to just extend an int and put a file descriptor in a struct and implement
- * send_data. Note that if you are using a higher-level net library that may call close() itself,
- * be careful to ensure you don't have races whereby you might register a new connection with an
- * fd which is the same as a previous one which has yet to be removed via
- * PeerManager::socket_disconnected().
+ * Two descriptors may compare equal (by [`cmp::Eq`] and [`hash::Hash`]) as long as the original
+ * has been disconnected, the [`PeerManager`] has been informed of the disconnection (either by it
+ * having triggered the disconnection or a call to [`PeerManager::socket_disconnected`]), and no
+ * further calls to the [`PeerManager`] related to the original socket occur. This allows you to
+ * use a file descriptor for your SocketDescriptor directly, however for simplicity you may wish
+ * to simply use another value which is guaranteed to be globally unique instead.
*/
@SuppressWarnings("unchecked") // We correctly assign various generic arrays
public class SocketDescriptor extends CommonBase {
protected void finalize() throws Throwable {
if (ptr != 0) { bindings.SocketDescriptor_free(ptr); } super.finalize();
}
-
+ /**
+ * Destroys the object, freeing associated resources. After this call, any access
+ * to this object may result in a SEGFAULT or worse.
+ *
+ * You should generally NEVER call this method. You should let the garbage collector
+ * do this for you when it finalizes objects. However, it may be useful for types
+ * which represent locks and should be closed immediately to avoid holding locks
+ * until the GC runs.
+ */
+ public void destroy() {
+ if (ptr != 0) { bindings.SocketDescriptor_free(ptr); }
+ ptr = 0;
+ }
public static interface SocketDescriptorInterface {
/**
* Attempts to send some data from the given slice to the peer.
*
* Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
- * Note that in the disconnected case, socket_disconnected must still fire and further write
- * attempts may occur until that time.
+ * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
+ * called and further write attempts may occur until that time.
*
- * If the returned size is smaller than data.len(), a write_available event must
- * trigger the next time more data can be written. Additionally, until the a send_data event
- * completes fully, no further read_events should trigger on the same peer!
+ * If the returned size is smaller than `data.len()`, a
+ * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
+ * written. Additionally, until a `send_data` event completes fully, no further
+ * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
+ * prevent denial-of-service issues, you should not read or buffer any data from the socket
+ * until then.
*
- * If a read_event on this descriptor had previously returned true (indicating that read
- * events should be paused to prevent DoS in the send buffer), resume_read may be set
- * indicating that read events on this descriptor should resume. A resume_read of false does
- * not* imply that further read events should be paused.
+ * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
+ * (indicating that read events should be paused to prevent DoS in the send buffer),
+ * `resume_read` may be set indicating that read events on this descriptor should resume. A
+ * `resume_read` of false carries no meaning, and should not cause any action.
*/
long send_data(byte[] data, boolean resume_read);
/**
- * Disconnect the socket pointed to by this SocketDescriptor. Once this function returns, no
- * more calls to write_buffer_space_avail, read_event or socket_disconnected may be made with
- * this descriptor. No socket_disconnected call should be generated as a result of this call,
- * though races may occur whereby disconnect_socket is called after a call to
- * socket_disconnected but prior to socket_disconnected returning.
+ * Disconnect the socket pointed to by this SocketDescriptor.
+ *
+ * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
+ * call (doing so is a noop).
*/
void disconnect_socket();
/**
impl_holder.held = new SocketDescriptor(new bindings.LDKSocketDescriptor() {
@Override public long send_data(byte[] data, boolean resume_read) {
long ret = arg.send_data(data, resume_read);
+ Reference.reachabilityFence(arg);
return ret;
}
@Override public void disconnect_socket() {
arg.disconnect_socket();
+ Reference.reachabilityFence(arg);
}
@Override public boolean eq(long other_arg) {
SocketDescriptor ret_hu_conv = new SocketDescriptor(null, other_arg);
- ret_hu_conv.ptrs_to.add(this);
+ if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
boolean ret = arg.eq(ret_hu_conv);
+ Reference.reachabilityFence(arg);
return ret;
}
@Override public long hash() {
long ret = arg.hash();
+ Reference.reachabilityFence(arg);
return ret;
}
});
* Attempts to send some data from the given slice to the peer.
*
* Returns the amount of data which was sent, possibly 0 if the socket has since disconnected.
- * Note that in the disconnected case, socket_disconnected must still fire and further write
- * attempts may occur until that time.
+ * Note that in the disconnected case, [`PeerManager::socket_disconnected`] must still be
+ * called and further write attempts may occur until that time.
*
- * If the returned size is smaller than data.len(), a write_available event must
- * trigger the next time more data can be written. Additionally, until the a send_data event
- * completes fully, no further read_events should trigger on the same peer!
+ * If the returned size is smaller than `data.len()`, a
+ * [`PeerManager::write_buffer_space_avail`] call must be made the next time more data can be
+ * written. Additionally, until a `send_data` event completes fully, no further
+ * [`PeerManager::read_event`] calls should be made for the same peer! Because this is to
+ * prevent denial-of-service issues, you should not read or buffer any data from the socket
+ * until then.
*
- * If a read_event on this descriptor had previously returned true (indicating that read
- * events should be paused to prevent DoS in the send buffer), resume_read may be set
- * indicating that read events on this descriptor should resume. A resume_read of false does
- * not* imply that further read events should be paused.
+ * If a [`PeerManager::read_event`] call on this descriptor had previously returned true
+ * (indicating that read events should be paused to prevent DoS in the send buffer),
+ * `resume_read` may be set indicating that read events on this descriptor should resume. A
+ * `resume_read` of false carries no meaning, and should not cause any action.
*/
public long send_data(byte[] data, boolean resume_read) {
long ret = bindings.SocketDescriptor_send_data(this.ptr, data, resume_read);
+ Reference.reachabilityFence(this);
+ Reference.reachabilityFence(data);
+ Reference.reachabilityFence(resume_read);
return ret;
}
/**
- * Disconnect the socket pointed to by this SocketDescriptor. Once this function returns, no
- * more calls to write_buffer_space_avail, read_event or socket_disconnected may be made with
- * this descriptor. No socket_disconnected call should be generated as a result of this call,
- * though races may occur whereby disconnect_socket is called after a call to
- * socket_disconnected but prior to socket_disconnected returning.
+ * Disconnect the socket pointed to by this SocketDescriptor.
+ *
+ * You do *not* need to call [`PeerManager::socket_disconnected`] with this socket after this
+ * call (doing so is a noop).
*/
public void disconnect_socket() {
bindings.SocketDescriptor_disconnect_socket(this.ptr);
+ Reference.reachabilityFence(this);
}
/**
*/
public long hash() {
long ret = bindings.SocketDescriptor_hash(this.ptr);
+ Reference.reachabilityFence(this);
+ return ret;
+ }
+
+ @Override public int hashCode() {
+ return (int)this.hash();
+ }
+ long clone_ptr() {
+ long ret = bindings.SocketDescriptor_clone_ptr(this.ptr);
+ Reference.reachabilityFence(this);
return ret;
}
*/
public SocketDescriptor clone() {
long ret = bindings.SocketDescriptor_clone(this.ptr);
+ Reference.reachabilityFence(this);
+ if (ret >= 0 && ret <= 4096) { return null; }
SocketDescriptor ret_hu_conv = new SocketDescriptor(null, ret);
- ret_hu_conv.ptrs_to.add(this);
+ if (ret_hu_conv != null) { ret_hu_conv.ptrs_to.add(this); };
return ret_hu_conv;
}
projects / ldk-java / blobdiff