FreeRTOS-Plus-TCP: FreeRTOS_select incorrect return value documentation

I’m adding a signal functionality to TCP sockets and noticed a mismatch between the documentation and what the select function actually does.

The return value of FreeRTOS_select is documented differently in 2 places and both of them seem to be incorrect:

  1. FreeRTOS_select and FreeRTOS_SignalSocket documentation state that FreeRTOS_select returns -pdFREERTOS_ERRNO_EINTR if a socket in a set receives a signal. It never does that, it returns eSELECT_INTR instead.

  2. Comment in FreeRTOS_Sockets.c state that returned value is:

@return The socket which might have triggered the event bit.

This is also not true, the select function returns event bits, not a socket.

Hello @Igor_Petrov,

Thank you for catching this discrepancy in our documentation and notifying us about it. We will work on fixing this quickly. Note that we do not update the website every day and it will get updated with the next scheduled update (mostly within a week).

As far as the documentation in comments is concerned, would you like to create a PR to the FreeRTOS-Plus-TCP repository, or would you like us to do that on your behalf?

Thanks,
Aniruddha

Hello @kanherea
I would prefer if you open a PR on my behalf

Hello @Igor_Petrov,

We have opened a PR and are working on merging it. Here is the link to the PR if you would like to review it: Updated comments for FreeRTOS_select return value by tony-josi-aws · Pull Request #596 · FreeRTOS/FreeRTOS-Plus-TCP · GitHub.

Additionally, we are working on updating the website description too. It should be updated with the next bulk update to the website.

Thanks again,
Aniruddha

Hello @Igor_Petrov, thank you for mentioning the incorrect comments.

Are you using the signal function in your projects? If so, does it work properly for you?

The socket-signal function was added on request of a wolfSSL user who wanted to interrupt a blocking call to FreeRTOS_recv(), in order to send a packet.

There are more ways to solve this, but in this case, a xxxFromISR() version was needed.

I tested this feature in a Xilinx project, which gets a hardware interrupt from a button. The GPIO interrupt will call FreeRTOS_SignalSocketFromISR(), which in case signals a socket.

@htibosch, my use case is a little different.
I’m implementing a single-task TCP server that serves a small number of clients. Basically this Server socket example, but instead of spawning a new task for the connected client, I have a socket set that contains listening socket and all connected clients. I wait by FreeRTOS_select for the incoming connection or data. If select unblocks because of eSELECT_READ event on the listening socket, I accept the connection, and add the accepted socket to the list of clients and to the socket set; else I search the list of connected clients for the socket that has eSELECT_READ set, read the data, process it and send the reply.

At some point during the program’s runtime, I need to shut down the server and gracefully close all connections. So there’s another task that sends the signal by FreeRTOS_SignalSocket to the listening socket indicating that it’s time to close everything and delete the server task. Of course, this could be implemented by setting a short blocking time in FreeRTOS_select call and pooling some flag, but I wanted to minimize pooling overhead and latency.

So far It works petty well. However, I haven’t tried to unblock FreeRTOS_recv calls or sent signals from ISR.