Question

I’m refactoring an old C code. The code has absolutely no layered architecture (everything is being accessed by everything) and I’m trying to change that.

I would like to cut direct access to structure members (at least write for now) and only allow access through access functions. Is there some tool (or perhaps directly the compiler) that could check this rule for me?

I need this since I’m maintaining a fork and the upstream isn’t very concerned with code quality.

Answer 1

The best way to ensure no new code accesses structures directly is to not make them available using total encapsulation. This comes at the cost of not being able to use a structure on the stack anymore. You provide a function to allocate the structure, another to free it, and all module functions accept a pointer to the structure. However, the definition of the structure itself is in the C file, and not the header file. Another disadvantage is that you may need to write a lot of functions to manipulate/query the structure.

I will provide snippets from an old code base where I’ve used this approach. The header contains:

#ifndef INC_QUEUE_H
#define INC_QUEUE_H

typedef enum {
    QUE_OK,
    QUE_BAD_PARAM,
    QUE_NO_MEMORY,
    QUE_SYS_ERROR
} QUE_RV;

typedef struct Queue_st Queue_t;

QUE_RV QUE_New(Queue_t **ppQueue);
QUE_RV QUE_Put(Queue_t *pQueue, int priority, void *pData);
QUE_RV QUE_Get(Queue_t *pQueue, int *priority, void **ppData);
void QUE_Free(Queue_t *pQueue);

#endif /* INC_QUEUE_H */

The C file defines the structure Queue_st, and implementations of the functions (heavily modified to highlight the approach):

#include "queue.h"
#include "log.h"

#define QUE_INITIAL_CAPACITY 128

struct Queue_st {
    /* SNIP: structure contents go here */
};

QUE_RV QUE_New(Queue_t **ppQueue)
{
    QUE_RV rv;

    *ppQueue = malloc(sizeof(Queue_t));

    /* SNIP: Check malloc, Initialize the structure here ... */

    return QUE_OK;
}

void QUE_Free(Queue_t *pQueue)
{
    if (pQueue != NULL)
    {
        /* SNIP: Free contents of the structure before the free below... */
        free(pQueue);
    }
}

An alternative approach is to use typedef struct StructName *StructHandle;, and replace all the pointers in the API with StructHandle. One less * to worry about.

---

EDIT: If you want some members visible, and some not, it is also possible with an extension of the above approach. In your header, define:

typedef struct StructPriv StructPriv;

typedef struct {
    /* public members go here */

    StructPriv *private;
} Struct;

Struct *STRUCT_Create();
void STRUCT_Free();

In the C file, define the private members, and the functions that manipulate them.