The font server uses the same client/server model as X. The basic structure is that of the X Consortium X11R5 X server, and those who know that code should find the os and difs (device independent font server) layers familiar.

                        ┌─────────────────┐
                  ┌─────┤      difs       ├──────┐
                  │     └─────────────────┘      │
                  │                              │
                ┌─┴──┐                  ┌────────┴───┐
                │ os │                  │ renderers  │
                └────┘                  └────────────┘
    

At startup, the font server handles any command line arguments, initializes any OS-specific data, and then sets up the communications. Various internal databases are then initialized (extensions, the font catalogue, etc).

The config file, an ordered list of font sources, cache size hints, default resolutions, and security information, is then read in. Each of these source names could be a directory name, the name of another font server, or some other string that a particular renderer can recognize.

The default font catalogue is then built up by taking each of the font source names and comparing it with the names a renderer recognizes. The one that matches this name will become attached to this source. A renderer will “understand” a name if it can parse the data in that directory, or recognize that it is a valid font server address, or recognizes a special string. Thus a collection of valid font path elements is built up. Each FPE has a set of functions to support opening a font and accessing its data.

Font information is accessed via method functions in the Font. When a font is first loaded, the header information and properties are loaded/computed. The font also initializes its function pointers to do the proper work. When specific metrics or bitmaps are required, they are access via the font's functions. A disk-based bitmap font will probably want to load all data when first accessed. A scaled font or FS font may want to do more selective caching. In both cases, the renderer can use the utility functions to keep track of this data. Changing values of bitmap formats could result in the font having multiple copies of data in different formats, which the renderer may use the utility functions to manage.

Each entity attaching to the server is a client. Each client has its own authorization and resolution information, and its own view of the font database. A font open to one client may not be open to another, though the font server may have it loaded.

After initialization, new clients can attach to the font server and have their requests processed. For each request that is searching for a font (OpenBitmapFont) or listing font names (ListFonts, ListFontsWithXInfo), the pattern is given to each FPE.

OpenBitmapFont will take the supplied name and pass it to each FPE. The FPE will return one of three things: Success, and the font object; BadFont, because it doesn't know the font; or BadFont and an alias name, when it has an alias for the font. If Success is returned, the server goes on to create an ID (or find an existing one) and return a reply. If BadFont is returned, it goes on to the next FPE. If it reaches the end without finding a font, an error is returned to the client. If an alias is returned, the search resets to the first FPE and starts again, using the alias as the new font name. This allows aliases to work across different FPEs, without any ordering restrictions.

When each FPE receives a font name to open, it searches for the font's existence. If it can't find, or can only find an alias, it returns BadFont and any alias. If it finds the font, it checks the authorization and license status of the font to that of the client. If it passes, it then creates a new font object, and reads and/or computes at least the font's header information and properties. (It may also want to produce the bitmaps and extents, but that choice is left to the renderer.)

When a font's information is accessed, the interpreter routine looks up the font ID to find the font object, and then uses the font's access functions to get the data. These functions will return the data in the format expected by the client.

When a client disconnects, all its references to any fonts it still has opened are removed. If no other clients reference these fonts, they may be freed, though the server may choose to cache them.

A server may be reset to flush the caches, re-read the configuration file, and a new list of FPEs to be built, via an OS-specific outside action. In UNIX, this will be handled via signals; in VMS it could be handled via an async trap or event flag.

In order to deal with numerous clients without major performance degradation, the server must be able to clone itself, or provide the client with a substitute server via the alternate server mechanism. Since both strategies have their uses, both will be supported. For a server that has plenty of host memory or CPU, but insufficient sockets, cloning may be a good choice. For a host with limited memory, assigning an alternate server on a different host may be a good choice. The server will make this decision based on configuration options.

The Client handles per-client information and interpreter status.

typedef struct _Client {
    int         index;
    pointer     osPrivate;
    int         noClientException;
    int         (**requestVector) ();
    pointer     requestBuffer;
    int         clientGone;
    int         sequence;
    Bool        swapped;
    long        last_request_time;
    void        (*pSwapReplyFunc) ();
    AuthContextPtr auth;
    char       *catalogues;
    int         num_catalogues;
    Mask        eventmask;
    fsResolution *resolutions;
    int         num_resolutions;
}           ClientRec, *ClientPtr;
    

The Font contains basic font information, including header information and properties.

typedef struct _font	{
	int	refcount;
	fsHeader	header;
	fsBitmapFormat	format;
	int	(*get_glyphs)();
	int	(*get_metrics)();
	int	(*get_extents)();
	int	(*get_bitmaps)();
	int	(*unload_font)();
	FontPathElementPtr	fpe;
	int	*client_ids;
	Bool	restricted_font;
}	FontRec *FontPtr;
    

The ClientFont is a wrapper on top of Font, handling client specific font information.

typedef struct _clientfont {
	FontPtr	font;
	int	clientindex;
}	ClientFontRec, *ClientFontRec;
    

The AuthContext contains authorization information.

typedef 	struct _authcontext	{
	char	*authname;
	char	*authdata;
	FSID	acid;
}	AuthContextRec *AuthContextPtr;
    

These functions are associated with each renderer, and handle all aspects of font access. Font data access is controlled via another set of functions described later. These functions are intended to support the R5 X server as well as the font server. As a result, some design decisions were made to support both models. When the difs layer needs to access a font, it uses these functions.

typedef unsigned long Mask;
typedef unsigned char *pointer;

typedef struct _FontPathElement {
    int         name_length;
    char       *name;
    int         type;
    int         refcount;
    pointer     private;
}           FontPathElementRec, *FontPathElementPtr;
    

The FPE's reference count is incremented when it is added to the current list of FPEs and when it opens a font. It is decremented when it is no longer in the current list and when it closes a font. All reference changes are handled by the difs layer. The count is required to support font catalogue changes that may occur while the fontserver has fonts open, and keeps FPEs from being lost.

typedef struct FontNames {
    int	nnames;
    int	size;
    int	*length;
    char	**names;
}	    FontNamesRec, *FontNamesPtr;

typedef struct {
	Bool	(*name_check)();
	int	(*init_fpe)();
	int	(*reset_fpe)();
	int	(*free_fpe)();
	int	(*open_font)();
	int	(*close_font)();
	int	(*list_fonts)();
	int	(*start_list_fonts_with_info)();
	int	(*list_next_font_with_info)();
	int	(*wakeup_fpe)();
	int	(*client_died);
	FontNamesPtr	renderer_names;
} FPEFunctions;

int	init_fpe_type(Bool (name_func)(),
		int (init_func)(), int (free_func)(), int (reset_func),
		int (open_func)(), int (close_func)(),
		int (list_func)(),
		int (start_lfwi_func)(), int (next_lfwi_func)(),
		int (wakeup_func)(),
		int (client_died_func)()
		)
    

This is called by the renderer when it is initialized at the beginning of time, and sets up an FPEFunctions entry for the renderer.

The FPEFunctions have the following parameters:

Bool	name_check(char *name);
      

If name is something the renderer recognizes as a valid font source name, it returns True, otherwise False. ie, if name is a directory name, or is prefixed by the renderer's prefix, and the directory contains font data the renderer can interpret, it would return True.

int	init_fpe(FontPathElementPtr fpe);
      

Does any initialization work for the renderer. The name in fpe will be one whose prefix matches the list returned when the renderer was initialized.

int	reset_fpe(FontPathElementPtr fpe);
      

Tells fpe to reset any internal state about what fonts it has available. This will typically be called because the font server's FPE search list has been changed. The fpe should reset any cached state of available fonts (ie, re-read fonts.dir)

int	free_fpe(FontPathElementPtr fpe);
      

Frees any renderer-specific data and closes any files or sockets.

int	open_font(pointer client, FontPathElementPtr fpe, Mask flags,
		  char *fontname, int namelength,
		  fsBitmapFormat format_hint, fsBitmapFormatMask format_mask,
		  XID fontid, FontPtr *ppfont, char **alias);
      

Opens the font. The bits marked by format_mask and format_hint are used where applicable. The resulting FontPtr is returned in ppfont. The client is optional state information for use with blocking renderers. If the fontname resolves to an alias, it is returned in alias with a FontNameAlias error. This tells the calling code to start searching again, using alias as the font name. The renderer is expected to fill in any information specified by the flags.

Possible flags values are:

#define FontLoadInfo    0x0001		/* font header info */
#define FontLoadProps   0x0002		/* font properties */
#define FontLoadMetrics 0x0004		/* font extents */
#define FontLoadBitmaps 0x0008		/* glyph bitmaps */
#define FontLoadAll     0x000f
#define FontOpenSync    0x0010		/* force synchronous loading */
      

Once a font has been opened, the server may place it and the pattern it matched into a name cache, to avoid lengthy searching if the font is reopened. If the renderer does not wish the font to be in this cache (for licensing reasons), it should set the font's restricted_access flag.

int	close_font(FontPtr pfont);
      

Frees up all the data associated with the font.

int	list_fonts(pointer client, FontPathElementPtr fpe,
		char *pattern, int pattern_length, int maxnames,
		FontNamesPtr *paths);
      

Returns in paths up to maxnames font names the fpe recognizes as matching the given pattern.

int	start_list_fonts_with_info(pointer client,
		FontPathElementPtr fpe, char *pattern, int pattern_length,
		int maxnames, pointer fpe_data);
      

Initiates a ListFontsWithXInfo. Typically, a disk-based renderer will do the equivalent of ListFonts to gather all the font names matching the pattern. A font server renderer will send the request. fpe_data provides a handle for any FPE-private data that needs to be passed in later via list_next_font_with_info(), eg, the list of font names for a disk-based renderer.

int	list_next_font_with_info(pointer client, FontPathElementPtr fpe,
		char **name, int *namelen, FontInfoPtr *pinfo,
		int *num_fonts, pointer fpe_data);
      

Returns the next font's information. The renderer should keep any state it requires in the fpe_data field. num_fonts contains the number of replies remaining.

These two routines are split for because of the way both disk-based renderers and font server renderers handle this request. The first function initiates the action, the second is used to gather the results. For a disk-based renderer, a list of font names matching the pattern is first built up when start_list_fonts_with_info()is called, and the results are gathered with each call to list_next_font_with_info(). In a font server renderer, the first function sends the ListFontsWithXInfo request, and the second processes the replies.

int	wakeup_fpe(FontPathElementPtr fpe, unsigned long *mask)
    

Optional function which can be used for blocking renderers. Typical usage is for a font server renderer, where it is called when a reply is received, allowing the data to be read and the client to be signaled and unblocked.

int	client_died(pointer client, FontPathElementPtr fpe)
      

This function is called when a client dies in the middle of a blocked request, allowing the renderer to clean up.

These functions are contained in each Font. For many renderers, every font will use the same functions, but some renderers may wish to use different interfaces for different fonts.

typedef struct {
	INT16	left B16,
		right B16;
	INT16	width B16;
	INT16	ascent B16,
		descent B16;
	CARD16	attributes B16;
}	fsCharInfo;

typedef struct {
    CARD8	low,
		high;
}           fsChar2b;

typedef struct {
    fsChar2b	min_char,
		max_char;
}           fsRange;

int	get_extents(pointer client,
		FontPtr pfont, Mask flags, int num_ranges, fsRange *ranges,
		int *num_extents, fsCharInfo **extents);
    

Possible flags:

LoadAll		/* ignore the ranges and get everything */
FinishRange	/* magic for range completion as specified by protocol */
    

Builds up the requested array of extents. The extent data (which the renderer allocates) is returned, as well as the number of extents. closure contains any blocking state information.

int	get_bitmaps(pointer client,
		FontPtr pfont, fsBitmapFormat format, Mask flags,
		int num_ranges, fsRange *ranges,
		unsigned long *size, unsigned long *num_glyphs,
		unsigned long **offsets, pointer *glyph_data);
    

Possible flags:

LoadAll
FinishRange	/* magic for range completion as specified by protocol */
    

Builds up the requested array of bitmaps. The glyph and offset data (which the renderer allocates) is returned, as well as the number of glyphs. The closure contains any blocking state information. This function will build up the bitmap data in the format specified by format so that the interpreter can return it without any additional modification. This should minimize data massaging, since outline renderers will hopefully be able to produce the bitmaps in the proper format.

void	unload_font(FontPtr pfont)
    

The render will free any allocated data. Note that the FPE function close_font() will also be called, and should handle any FPE data allocated for the font.

int	get_glyphs()
int	get_metrics()
    

These two functions are used by the X server for loading glyphs and metrics. They expect the results in a considerably different form. The get_bitmaps() and get_extents() routines both allow for better cache control by the renderer.

Existing bitmap renderers already have their own concept of font organization. In the X sample server, the files fonts.dir and fonts.alias are used to list the known fonts. fonts.dir maps file names to font names, while fonts.alias maps font names to other font names.

These concepts will also be needed by other forms of fonts which the sample X server does not currently use, but the font server will, like Bitstream outlines.

For those renderers that support scalable fonts, several issues must be addressed:

The font server will also support large grain security. It will have both a limit of the number of users, and on the hosts which it will support.

Limiting the number of users is as much a server loading issue as a security issue. The limitation will be typically be set via configuration options or OS limitations. To change it, use:

void	AccessSetConnectionLimit(int limit)
    

A limit of 0 will set it to a compiled constant based on OS resources (eg, number of file descriptors).

Client-host based access control can be used to supplement licensing, and support font server load balancing by restricting access. As with licensing, this is OS-specific code. To manipulate these functions, use:

typedef struct _host_address {
	int	type;
	pointer	address;
	struct _host_address *next;
} HostAddress;

typedef HostAddress	*HostList;

int	AddHost(HostList list, HostAddress *address)
int	RemoveHost(HostList list, HostAddress *address)
Bool	ValidHost(HostList list, HostAddress *address)
    

AddHost() adds a host to the list. RemoveHost() removes it, and ValidHost() checks to see if its on the list. In all functions, the address will ignore any value in the next field.

Network addresses are used here to avoid issues with host name aliases. The caller fills in the desired type, and an address of that form is returned. This is highly OS-specific, but values for the type and address fields could include:

#define	HOST_AF_INET	1
struct in_addr	*address;

#define	HOST_AF_DECnet	2
struct	dn_addr	*address;
      

The server will use a global host list, but having the list as an argument will allow licensing schemes to have their own host lists.

Licensing is a tricky issue, which each renderer will support in a different way. The sample font server will attempt to provide some guidelines, and present a possible implementation of some simple licensing schemes.

void	GetHostAddress(HostAddress *address);
      

This contains the protocol dispatcher, interpreter and reply encoding routines.

The interpreter is table driven off the request code. The dispatcher gets a request from the os layer from WaitForSomething(), and uses the request code to determine which function to call. eg, a CloseFont request would call ProcCloseFont().

Each request's routine handles any applicable error checking, and then does as much work as it can. For font related requests, this means converting the request to the proper arguments for the renderers.

If any replies are generated, the reply data is gathered into the bytestream format, and sent via os write functions to the client.

If the byte order of the client and server differ, the above is modified by having the dispatcher call an intermediate function which re-orders the request to the proper byte order. Replies go through similar swapping.

Bool	ClientSleep(ClientPtr client, Bool (*function)(), pointer closure)
      

      Bool ClientSignal(ClientPtr client)
      

      void ClientWakeup(ClientPtr client)
      

      Bool ClientIsAsleep(ClientPtr client)
      

This layer contains OS specific routines for configuration, command line parsing, client/server communications, and various OS-dependent utilities such as memory management and error handling.

ReadRequestFromClient() returns a full request to the dispatcher. WaitForSomething() is where the server spends its idle time, waiting for any action from a client or processing any work left from a blocked client.

When a client attempts to connect, the server will call

int	CheckClientAuthorization(ClientPtr client, AuthPtr client_auth,
		int *accept, int *index, int *size, char **authdata)
      

to see if the server is set to allow the client to connect. It may use licensing or configuration information to determine if the client can connect.

When then connection is established, the server will use the

typedef struct _alt_server {
    char        subset;
    char        namelen;
    char       *name;
}           AlternateServerRec, *AlternateServerPtr;

int	ListAlternateServers(AlternateServerPtr *servers)
      

to return any alternate server information it may have.

When the client limit is reached, the font server may attempt to copy itself, by calling

int	CloneMyself()
    

This function will (if the configuration options allow) start a new font server process. This is done in such a way that no pending connections should be lost, and that the original server will accept no new connections. Once the original server has no more clients, it will exit.

int	ListCatalogues(char *pattern, int pattern_length,
		       int maxnames, char **catalogues, int *len)
      

int ValidateCatalogues(int number, char *catalogues)
      

This section describes in-depth the action of each protocol request. In all cases, the request is first error checked for simple length or value errors, with the server immediately returning an error if one is encountered.

The configuration mechanism is a simple keyword-value pair, separated by an '='.

Each renderer may also want private configuration options. The names should be prefixed by the renderer name, ie pcf-, atm-.

# allow a ~a megabyte of memory to be reserved for cache data
cache-size = 1000000

catalogue = pcf:/usr/lib/X11/fonts/misc,speedo:/usr/lib/fonts/speedo