C++ – Interface design where functions need to be called in a specific sequence

cinterfaces

The task is to configure a piece of hardware within the device, according to some input specification. This should be achieved as follows:

1) Collect the configuration information. This can happen at different times and places. For example, module A and module B can both request (at different times) some resources from my module. Those 'resources' are actually what the configuration is.

2) After it is clear that no more requests are going to be realized, a startup command, giving a summary of the requested resources, needs to be sent to the hardware.

3) Only after that, can (and must) detailed configuration of said resources be done.

4) Also, only after 2), can (and must) routing of selected resources to the declared callers be done.

A common cause for bugs, even for me, who wrote the thing, is mistaking this order. What naming conventions, designs or mechanisms can I employ to make the interface usable by someone who sees the code for the first time?

Best Answer

It's a redesign but you can prevent misuse of many APIs but not having available any method that shouldn't be called.

For example, instead of first you init, then you start, then you stop

Your constructor inits an object that can be started and start creates a session that can be stopped.

Of course if you have a restriction to one session at a time you need to handle the case where someone tries to create one with one already active.

Now apply that technique to your own case.

Related Solutions

C++ – Understanding Reference Operator in Specific Functions

A reference serves one purpose: to act as an alias for an existing variable:

int i;
int &ri = i;

In this example, the addresses of i and ri are identical (&i == &ri). The two names refer to the very same location in memory. Thus one of the useful applications of references is to provide an alias for a long name that it would be wasteful to retype:

const Location& p = irresponsibly_long_object_name.retrieve_location();

When you pass a function parameter by reference, it has the same effect:

void increment(int& parameter) { ++parameter; }

int main(int argc, char** argv) {
    int variable = 0;
    increment(variable);
}

Here, parameter serves merely as an alias of variable, just as though it were defined as int& parameter = variable. Modifying parameter inside increment() is indistinguishable from modifying variable in main(). Furthermore—and this is quite useful—variable does not need to be copied; so if it were of a large type such as std::list<int>, then passing it by reference would be much more efficient. That’s the main point of const references.

For the purpose of function parameters of reference type, the sanest course of action for a compiler is to use a pointer internally, as if you had written:

void increment(int* parameter) { ++*parameter; }

int main(int argc, char** argv) {
    int variable = 0;
    increment(&variable);
}

This is an interesting detail, and well worthwhile to remember. While it is not essential to your understanding of references, recognising this equivalence allows you to think of pointers merely as explicit references. Likewise, references are implicit pointers.

C++ class with only pure virtual functions: what’s that called

The technical term for a class with a pure virtual function is abstract class, but that terms also applies if the class has additional non-pure virtual functions.

Often the term Interface is used in C++ to describe an abstract class like Printable, that describes a service that can be provided by a range of different, otherwise unrelated classes. This corresponds to the use of the interface keyword in C#/Java.

I have never encountered the term 'protocol' in connection with a C++ class

Best Answer

Related Solutions

C++ – Understanding Reference Operator in Specific Functions

C++ class with only pure virtual functions: what’s that called

Related Topic