What to choose, ioctl-like interface or a set of distinct methods?

Question

I am implementing a messaging protocol between nodes on a network and i am wondering how to expose the messaging system interface to the programmers. The messaging protocol supports a set of commands that the clients and servers can exchange to get jobs done.

To be generic, let's says, for instance, the system supports 2 operations : REQUEST_OBJECT, MODIFY_OBJECT. To provide an interface, i have 2 choices : Whether to provide 2 distinct methods : request_object (handle, obj) and modify_object (handle, obj, data) or use a generic method : msg_ioctl (handle, COMMANDE, var_args ...), the number of variadic arguments var_args ... and their interpretation depends exclusively on COMMANDE so in this case we will have 2 different cases for the ioctl call : msg_ioctl (handle, REQUEST, obj) and msg_ioctl (handle, MODIFY, obj, data).

What are the advantages and disadvantage of each option and what could be the possible flaws that can become visible in the long run taking in consideration different languages that are possibly to be used (To discuss things like argument type checking ...etc) to implement such a system ?

Answer 1

Whether to provide 2 distinct methods : request_object (handle, obj) and modify_object (handle, obj, data) or use a generic method : msg_ioctl (handle, COMMANDE, var_args ...)

Please use the former: two distinct methods.

In software, the consuming client interface is critical.  While the IOCTL approach has (..arguably) some implementation advantages, the distinct methods approach has major advantages to the consuming client.

IOCTL essentially mixes many operations together, whereas the other keeps them teased apart.

Kept apart, the IDE, search, etc.. are more effective.  This better supports refactoring and maintenance of the clients consuming the API.

Many things work better when methods are kept distinct, such as the type system — our first line of defense against bugs.  For another, the compiler will almost certainly generate better code at the call sites for the separate methods (with distinctly declared parameters) rather than for a single method that uses varargs.

In summary, we should not conflate otherwise distinct things   I can think of no real advantage for doing that in this case (other than the extremely minor implementation advantage of providing one less method for the API, and this even assuming that the implementation turns around and makes a similar (IOCTL-style) syscall).