Class SocketDescriptor


  • public class SocketDescriptor
    extends Object
    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. 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.
    • Method Detail

      • destroy

        public void destroy()
        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.
      • send_data

        public long send_data​(byte[] data,
                              boolean resume_read)
        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, [`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 [`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 [`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.
      • disconnect_socket

        public void disconnect_socket()
        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).
      • hash

        public long hash()
        Calculate a succinct non-cryptographic hash for an object given its this_arg pointer. This is used, for example, for inclusion of this object in a hash map.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object