Tor 0.4.9.0-alpha-dev
Macros
handles.h File Reference

Macros for C weak-handle implementation. More...

#include "orconfig.h"
#include "lib/log/util_bug.h"
#include "lib/malloc/malloc.h"

Go to the source code of this file.

Macros

#define HANDLE_ENTRY(name, structname)    struct name ## _handle_head_t *handle_head
 
#define HANDLE_DECL(name, structname_t, linkage)
 
#define HANDLE_IMPL(name, structname, linkage)
 

Detailed Description

Macros for C weak-handle implementation.

A 'handle' is a pointer to an object that is allowed to go away while the handle stays alive. When you dereference the handle, you might get the object, or you might get "NULL".

Use this pattern when an object has a single obvious lifespan, so you don't want to use reference counting, but when other objects might need to refer to the first object without caring about its lifetime.

To enable a type to have handles, add a HANDLE_ENTRY() field in its definition, as in:

struct walrus_t {
    HANDLE_ENTRY(wlr, walrus_t);
    // ...
};

And invoke HANDLE_DECL(wlr, walrus_t, [static]) to declare the handle manipulation functions (typically in a header):

// opaque handle to walrus.
typedef struct wlr_handle_t wlr_handle_t;

// make a new handle
struct wlr_handle_t *wlr_handle_new(struct walrus_t *);

// release a handle
void wlr_handle_free(wlr_handle_t *);

// return the pointed-to walrus, or NULL.
struct walrus_t *wlr_handle_get(wlr_handle_t *).

// call this function when you're about to free the walrus;
// it invalidates all handles. (IF YOU DON'T, YOU WILL HAVE
// DANGLING REFERENCES)
void wlr_handles_clear(struct walrus_t *);

Finally, use HANDLE_IMPL() to define the above functions in some appropriate C file: HANDLE_IMPL(wlr, walrus_t, [static])

Definition in file handles.h.

Macro Definition Documentation

◆ HANDLE_DECL

#define HANDLE_DECL (   name,
  structname_t,
  linkage 
)
Value:
typedef struct name ## _handle_t name ## _handle_t; \
linkage name ## _handle_t *name ## _handle_new( \
struct structname_t *object); \
linkage void name ## _handle_free_(name ## _handle_t *); \
linkage struct structname_t *name ## _handle_get(name ## _handle_t *); \
linkage void name ## _handles_clear(struct structname_t *object);
const char * name
Definition: config.c:2462

Definition at line 60 of file handles.h.

◆ HANDLE_ENTRY

#define HANDLE_ENTRY (   name,
  structname 
)     struct name ## _handle_head_t *handle_head

Definition at line 57 of file handles.h.

◆ HANDLE_IMPL

#define HANDLE_IMPL (   name,
  structname,
  linkage 
)

Definition at line 90 of file handles.h.