Is it reasonable to eliminate functionality that you're wrapping?

[stevieb]

This is a question of opinion on API usage, not a direct coding question.

I've got an API. This API calls underlying C functions. The author of the C library changed his mind to remove safety checks on a particular routine (eg: setup()), so that it no longer checks whether that function has been called or not.

In some of my Perl code, I do some due diligence and ensure we call the proper setup() in the right order, and ensure it is only called once.

The reason for the checks in the C code, is if an inexperienced or lazy coder calls the function too many times, it can result in a situation where no more system-wide file handles will be available, essentially, crashing the system.

There are five such setup routines. I'll depict them like this:

use constant {
    RPI_MODE_WPI => 0,
    RPI_MODE_GPIO => 1,
    RPI_MODE_GPIO_SYS => 2,
    RPI_MODE_PHYS => 3,
    RPI_MODE_UNINIT => -1,
};

Now, in my Perl code, I magically track any time a sub module runs to ensure that an already existing setup hasn't been executed. With the C restriction lifted, I *still* want to do this, but I want to drop support for all but the most-used routine (aka pin mapping scheme), which is GPIO.

In my distribution, I have removed all references for the routines I don't want used anymore in the documentation, but left them in code just in case (there's no legacy issue here, as nobody was really using my code before I made that decision).

My question, is whether from your perspective you'd keep true to the underlying C libraries you're wrapping, or sacrifice some convenience to some users, and make things much, much easier for yourself maintainability wise going forward.

Because this is Perlmonks, here's some code. This is some init code that actually aids in deciding whether a setup routine has been called or not. Yes, there are a lot of if/else stuff, but because I knew I'd approach what I'm asking here someday, I wanted it nice and open and free-flowing.

sub new {
    my ($self, %args) = @_;
    $self = bless {%args}, $self;

    if (! $ENV{NO_BOARD}){
        if (my $scheme = $ENV{RPI_PIN_MODE}){
            # this checks if another application has already run
            # a setup routine

            $self->pin_scheme($scheme);
        }
        else {
            # we default to gpio mode

            if (! defined $self->{setup}) {
                $self->SUPER::setup_gpio();
                $self->pin_scheme(RPI_MODE_GPIO);
            }
            else {
                if ($self->_setup =~ /^w/) {
                    $self->SUPER::setup();
                    $self->pin_scheme(RPI_MODE_WPI);
                }
                elsif ($self->_setup =~ /^g/) {
                    $self->SUPER::setup_gpio();
                    $self->pin_scheme(RPI_MODE_GPIO);
                }
                elsif ($self->_setup =~ /^p/) {
                    $self->SUPER::setup_phys();
                    $self->pin_scheme(RPI_MODE_PHYS);
                }
                elsif ($self->_setup =~ /^W/){
                    $self->pin_scheme(RPI_MODE_WPI);
                }
                else {
                    $self->pin_scheme(RPI_MODE_UNINIT);
                }
            }
        }
        # set the env var so we can catch multiple
        # setup calls properly

        $ENV{RPI_SCHEME} = $self->pin_scheme;
    }
    $self->_fatal_exit;
    return $self;
}

Removing all of the setup routines less the one I want would make it *tremendously* easier to support going forward maintenance-wise, as well as making things a lot more flexible in the long run. I can still perform the safety check, but a lot of code could be removed, and the checks would become much less aggressive and to put it bluntly, less fraught with potential holes.

I'm thinking remove. What do you think... maintainability or adhering to the underlying API?

[RonW]

Eventually, some one is going to want functionality that is in the library but not exposed by your Perl interface. Maybe even you. I don't know the maintenance burden, so I can't weigh the trade-offs.

I'm all for simplification. I have also gotten bitten many times by going to far.

I don't know what simplifications you would be making by removing the currently unused functionality, but maybe you can figure out a simpler way to provide the checks you already have.

Wish I could be more helpful. Just wanted to point out the potential downside.

[Anonymous Monk]

So you want to expose a part - the useful part - of the functionality and ignore the rest? Not a problem. All software have their scope and limits, whether explicit or not. Failure to grok this often leads to feature creep, performance issues, etc.

Just name your module appropriately. If it does GPIO, call it FOO::FooGPIO or somesuch.