RPC versioning

[Roland McGrath]

Here is an old message from another list that's relevant here.


Date: Sun, 7 Jan 2001 01:33:53 -0500 (EST)
From: Roland McGrath <address@hidden>
Subject: RPC versioning

I more or less have a plan for how to do versioning and compatibility for
the RPC interfaces.  I don't have a development environment these days, so
I just have a vague plan and no actual code or anything.  I could implement
this eventually, but I'm not really sure when, or someone else could do
something concrete based on my plan.

The concept is to use a cpp macro to define each RPC in the .defs file,
something like:

compat_routine (io_stat, VERS1, VERS2, (
        stat_object: io_t;
        RPT
        out stat_info: io_statbuf_t));
versioned_routine (io_stat, VERS2, (
        stat_object: io_t;
        RPT
        out stat_info: io_statbuf64_t));

In compat_routine, you give the version in which that RPC signature was
defined, and the version that obsoleted it.  

In the libc makefiles, we'll use this to produce the stubs and the version
map file for libhurduser.  We'll compile client RPC stubs called
io_stat_VERS1 and io_stat_VERS2.  In symbol version set VERS1,
io_stat_VERS1 will be called io_stat, and the other names won't exist since
that is the earliest version set containing that RPC.  In symbol version
set VERS2, that same stub will be called io_stat_VERS1, the new one will be
called both io_stat_VERS2 and io_stat.  If there is a future replacement in
a new version set (VERS9 say), then it will be called io_stat_VERS9 and
io_stat in that set; but you will always be able to use the names
io_stat_VERS1 and io_stat_VERS2.

In the hurd makefiles, we'll use the macros to produce the server-side
function names.  We can parameterize the macro definitions to make it easy
to produce compatible stubs for old server sources.  You specify the newest
VERSn to produce stubs for, and any newer ones just get "skip".  (You can
also specify the oldest version to produce compatibility stubs for, to
phase out old interfaces over time.)  It might be simplest just to always
use versioned names like <pfx>_S_io_stat_VERS1 for the server functions
once there is more than one version.  OTOH, using the unadorned name for
the newest one makes the server sources stay pretty.  We can also use
makefile hacks driven by these macros to help with the compatibility
functions.  I think we should write the makefiles so they barf on you if
you fail to provide a compatibility wrapper for an old RPC in
libiohelp/libfshelp.  We can also do a hack using either -defsym or a
linker script to rename the lib*help compatibility functions and what they
call to the appropriate names for the particular server/library that
implements the interface.