nsapi: Renamed attach -> sigio to decrease confusion on its behaviour

features/netsocket/Socket.cpp

@@ -149,11 +149,14 @@ nsapi_error_t Socket::getsockopt(int level, int optname, void *optval, unsigned
 
 }
 
-void Socket::attach(Callback<void()> callback)
+void Socket::sigio(Callback<void()> callback)
 {
     _lock.lock();
-
     _callback = callback;
-
     _lock.unlock();
 }
+
+void Socket::attach(Callback<void()> callback)
+{
+    sigio(callback);
+}

features/netsocket/Socket.h

@@ -163,22 +163,30 @@ public:
      *  The callback may be called in an interrupt context and should not
      *  perform expensive operations such as recv/send calls.
      *
+     *  Note! This is not intended as a replacement for a poll or attach-like
+     *  asynchronous api, but rather as a building block for constructing
+     *  such functionality. The exact timing of when the registered function
+     *  is called is not guaranteed and susceptible to change.
+     *
      *  @param func     Function to call on state change
      */
+    void sigio(mbed::Callback<void()> func);
+
+    /** Register a callback on state change of the socket
+     *
+     *  @see Socket::sigio
+     *  @deprecated
+     *      The behaviour of Socket::attach differs from other attach functions in
+     *      mbed OS and has been known to cause confusion. Replaced by Socket::sigio.
+     */
+    MBED_DEPRECATED_SINCE("mbed-os-5.4",
+        "The behaviour of Socket::attach differs from other attach functions in "
+        "mbed OS and has been known to cause confusion. Replaced by Socket::sigio.")
     void attach(mbed::Callback<void()> func);
 
     /** Register a callback on state change of the socket
      *
-     *  The specified callback will be called on state changes such as when
+     *  @see Socket::sigio
-     *  the socket can recv/send/accept successfully and on when an error
-     *  occurs. The callback may also be called spuriously without reason.
-     *
-     *  The callback may be called in an interrupt context and should not
-     *  perform expensive operations such as recv/send calls.
-     *
-     *  @param obj      Pointer to object to call method on
-     *  @param method   Method to call on state change
-     *
      *  @deprecated
      *      The attach function does not support cv-qualifiers. Replaced by
      *      attach(callback(obj, method)).