Family: PTB, cred
Author: Kevin S Braunsdorf
Mail: [email protected]
Version: 1.28
Bugs: none known

Introduction

These routines provide a control interface to the parallel token broker wrapper and other wrappers that use the same command frame-work, or need similar services.

Configuration

The only configuration option is the use of the socket credential service (CRED_SCM_MSG), or the emulation of same. For this service the file "machine.h" should define SCM_CREDS. 
#define SCM_CREDS 1
Which forces the generated code to include "cred.h" (which must be presented from the explode repository as well. In addition the code must be linked with (at least) "credsend.c" exploded from "cred.c".

Provides

extern int PTBClientPort(const char *pcDirect);

Returns a socket connected to the given wrapper socket. If SCM_CREDS is defined when compiled the local credentials are sent to the wrapper.

static unsigned int uOurCount, uOurSize;

Once PTBClientPort is successful, uOurCount holds the number of tokens the enclosing diversion holds, and uOurSize the total space required to hold the list of token names (including any '\000' string terminators).

extern char *PTBReadTokenList(int sMaster, unsigned int uNeed, unsigned int **ppuList);

Download uNeed token names from the master instance with the 'G' command. Fill ppuList with the vector of tokens we leased from the whole list, which is in malloc'd space.

extern unsigned int PTBFreeTokenList(int sMaster, unsigned int uHold, unsigned int *puList);

Release the token allocated by PTBReadTokenList with the 'D' command. The master diversion might give them to some other client process, so don't lie to it. Subsequent called to PTBReadTokenList might allocate a wholely different list, or fail.

extern int PTBCmdInt(int sMaster, int cCmd);

Send the master a command that must return an ASCII encoded base-10 interger; we return the interger, or -1 for an error with errno set. The resulting integer cannot have more than 63 digits in it. The return string may start with "-No" to force an errno of EINVAL. An explicit -1 sets errno to "Protocol not supported" (ENOTSUP, EPROTONOSUPPORT, or ENOPROTOOPT).

extern int PTBIsSocket(char *pcPath);

Returns non-zero if the Path is a socket, which might represent a master diversion.

extern int PTBReqSource(int sMaster, char *pcSource, size_t iMax, char **ppcMeta);

Request the source of the token stream with the 'U' command. If ppcMeta is not (char **)0, we also request the meta-information from the token stream (via 'C' command). We return the first character of the source; usually a '+' for success or a '-' for failure or an unknown source.

extern char *PTBIota(unsigned int uMax, unsigned int *puWidth);

Build the default token list that all token brokers use: the list of counting numbers from 1 to N. This is returned in the same format the list of tokens from a master would be returned (0 is a valid count which return the empty list).

extern int PTBQuit(int sMaster, char *pcReply, unsigned uLen);

Send any persistant diversion the 'Q' command. If the reply is a negative ("-No\n") return 0, otherwise 1.

extern int PTBReadPid(int sMaster, pid_t *pwMaster);

Use the 'M' command to ask the master for her process id. Return 0 for no master as well as any non-numeric reply.

To Do List

Nothing. 

$Id: ptbc.html,v 1.9 2012/03/29 21:14:06 ksb Exp $