const qualifiers in pubic API

[martinjrobins]

Is your feature request related to a problem? Please describe.

I'm writing a rust sys crate that uses bindgen to automatically generate rust bindings for suitesparse. At the moment when wrapping a function like klu_analyze in the KLU solver, raw pointers are wrapped as mutable pointers *mut T, e.g: the C function

KLU_symbolic *KLU_analyze       /* returns NULL if error, or a valid
                                   KLU_symbolic object if successful */
(
    /* inputs, not modified */
    Int n,              /* A is n-by-n */
    Int Ap [ ],         /* size n+1, column pointers */
    Int Ai [ ],         /* size nz, row indices */
    /* -------------------- */
    KLU_common *Common
)

becomes

extern "C" {
    pub fn klu_analyze(
        n: i32,
        Ap: *mut i32,
        Ai: *mut i32,
        Common: *mut klu_common_,
    ) -> *mut klu_symbolic_;
}

This is an issue because the arguments Ap and Ai are incorrectly marked as mutable, causing problems downstream for users who are then required to have mutable handles to Ap and Ai. This can be corrected by marking the arguments Ap and Ai in the C signature as const, for example:

KLU_symbolic *KLU_analyze       /* returns NULL if error, or a valid
                                   KLU_symbolic object if successful */
(
    /* inputs, not modified */
    Int n,              /* A is n-by-n */
    Int Ap [const],         /* size n+1, column pointers */
    Int Ai [const],         /* size nz, row indices */
    /* -------------------- */
    KLU_common *Common
)

which would then generate the correct rust function signature with Ap and Ai marked as `const.

Are there any plans to explicitly use const qualifiers in suitesparse rather than relying on comments like this? Would you be happy if I put together a PR adding this to the functions that I need?

Describe the solution you'd like

Use explicit const qualifiers in public facing functions.

Describe alternatives you've considered

The alternative is for the bindings for suitesparse be manually implemented, rather than relying on automated tools.

[mmuetzel]

I agree with your point. It would probably be best if function arguments that are pointers (or arrays) to variables that aren't allowed to be changed by the function were marked as const.

However, are you sure that Int Ap[const] is valid C syntax? Shouldn't it be const Int Ap[] instead?

[martinjrobins]

I believe you can do Int Ap[const] since C99 (https://en.cppreference.com/w/c/language/const#:~:text=In%20a%20function%20declaration%2C%20the,the%20array%20type%20is%20transformed.), but I'm not sure as this is the first time I've come across this syntax. Presumably const Int Ap[] is equivilent?

UPDATE: actually, after looking at https://en.cppreference.com/w/c/language/array I think const Int Ap[] is a pointer to an array of const Int values, whereas Int Ap[const] is a const pointer to an array of Int values, so I think you are correct it should be const Int Ap[], or perhaps even const Int Ap[const].

[DrTimothyAldenDavis]

This will take me quite a while to resolve, since I would need to revise all APIs to essentially all my packages. It might also require an SO change to all my packages as well. But I'll consider it for the future.

[gruenich]

Cppcheck detects pointer that are not modified and proposes a modification of the function signature. Tim, tell me one library to begin with and I will create an according merge request. From the changes you will have a good starting point what to revise. Are you interested?

[DrTimothyAldenDavis]

No. It would be too disruptive to existing applications that use my codes, if I were to change the user visible api.

Sent from Gmail Mobile

On Mon, Oct 28, 2024 at 5:34 PM Christoph Grüninger < @.***> wrote:

Cppcheck detects pointer that are not modified and proposes a modification of the function signature. Tim, tell me one library to begin with and I will create an according merge request. From the changes you will have a good starting point what to revise. Are you interested?

— Reply to this email directly, view it on GitHub https://github.com/DrTimothyAldenDavis/SuiteSparse/issues/845#issuecomment-2442800071, or unsubscribe https://github.com/notifications/unsubscribe-auth/AEYIION27OKNTUTAXCDFAV3Z52UWJAVCNFSM6AAAAABKAIHCNSVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDINBSHAYDAMBXGE . You are receiving this because you commented.Message ID: @.***>

[gruenich]

Tim, I see you concerns. What about a less disruptive approach using a toggle?

1. Introduce a C pre-processor macro SS_API_CONST
2. Introduce another C pre-processor macro and similar named CMake variable STRICT_API_CONST
3. Add this code at a central point:

   #ifdef STRICT_API_CONST
   #define SS_API_CONST const
   #else
   #define SS_API_CONST
   #endif

4. We can modify the public API like in

   KLU_symbolic *KLU_analyze       /* returns NULL if error, or a valid
                                  KLU_symbolic object if successful */
   (
   /* inputs, not modified */
   Int n,              /* A is n-by-n */
   SS_API_CONST Int Ap [ ],         /* size n+1, column pointers */
   SS_API_CONST Int Ai [ ],         /* size nz, row indices */
   /* -------------------- */
   KLU_common *Common
   )

5. By default, the API remains unchanged. If a user wants to use the improved API, she has to set the toggle.
6. In SuiteSparse 8 or 9 you can decide to activate the toggle always, and later replace every SS_API_CONST by const in SuiteSparse.

By the way, at SuperLU we have a similar discussion and currently no solution. The claim is that when the interfaces introduces consts, the user code can rely on this and be written to be a little bit faster. See https://github.com/xiaoyeli/superlu/issues/142

[DrTimothyAldenDavis]

Got it. That would be much less disruptive. Would the API changes be limited to just adding the const?