distLib

NAME

distLib - distributed objects initialization and control library (VxFusion)

ROUTINES

distInit( ) - initialize and bootstrap the current node
distCtl( ) - perform a distributed objects control function

DESCRIPTION

This library provides an initialization and control interface for VxFusion.
Use distInit( ) to initialize VxFusion on the current node. In addition to performing local initialization, distInit( ) attempts to locate remote VxFusion nodes on the network and download copies of the databases from one of the remote nodes.
Call distCtl( ) to set VxFusion run-time parameters using an ioctl( )-like syntax.

NOTE

In this release, the distInit( ) routine is called automatically with default parameters when a target boots using a VxWorks image with VxFusion installed.

INCLUDE FILES

distLib.h

distInit( )

NAME

distInit( ) - initialize and bootstrap the current node

SYNOPSIS

STATUS distInit
    (
    DIST_NODE_ID myNodeId,      /* node ID of this node */
    FUNCPTR      ifInitRtn,     /* interface adapter init routine */
    void *       pIfInitConf,   /* ptr to interface configuration */
    int          maxTBufsLog2,  /* max number of telegram buffers */
    int          maxNodesLog2,  /* max number of nodes in node db */
    int          maxQueuesLog2, /* max number of queues on this node */
    int          maxGroupsLog2, /* max number of groups in db */
    int          maxNamesLog2,  /* max bindings in name db */
    int          waitNTicks     /* wait n ticks when bootstrapping */
    )

DESCRIPTION

This routine initializes VxFusion on the current node. The routine begins by initializing the local databases and other internal services. As part of this process, the current node is given the address specified by the myNodeId argument.
Secondly, this routine links a network driver to the stack by calling the interface adapter initialization routine specified by the ifInitRtn argument. If the interface adapter initialization is successful, this routine then initializes the telegram buffer library which is needed for manipulating telegram buffers--the buffers that hold the packets sent between nodes.
Thirdly, this routine attempts to determine what other VxFusion nodes are active on the network. This is done by continually sending a BOOTSTRAP telegram, which indicates to other nodes that VxFusion is starting up on this node. Nodes that receive a BOOTSTRAP telegram answer by sending an XACK telegram. The XACK telegram contains information about the remote node. The sender of the first XACK received is the godfather for the current node. The purpose of the godfather is to update local databases. If no XACK is received within the amount of time specified by the waitNTicks argument, it is assumed that this node is the first node to come up on the network.
As soon as a godfather is located or it is assumed that a node sending an XACK is the first to do so on the network, the state of the node shifts from the booting state to the network state. In the network state, all packets are sent using reliable communication channels; therefore all packets must be now acknowledged by the receiver(s).
If a godfather has been located, the current node asks it to update the local databases by sending an INCO_REQ packet. The godfather then begins updating the local databases. When the godfather finishes the update, it sends an INCO_DONE packet to the node being updated.
Once the database updates have completed, the node moves into the operational state and broadcasts an INCO_UPNOW packet.
The number of telegram buffers pre-allocated is equal to 2^maxTBufsLog2.
Up to 2^maxNodesLog2 nodes can be handled by the node database.
The number of distributed message queues is limited to 2^maxQueuesLog2.
Distributed message queue groups may not exceed 2^maxGroupsLog2 groups.
The distributed name database can work with up to 2^maxNamesLog2 entries.

EXAMPLE

-> distInit (0x930b2610, distIfUdpInit, "ln0", 9, 5, 7, 6, 8, (4*sysClkRateGet())
This command sets the ID of the local node to 0x930b2610 (147.11.38.16). The distIfUdpInit( ) routine is called to initialize the interface adapter (in this case, a UDP adapter). The UDP adapter requires a pointer to the hardware interface name as configuration data (in this case, "ln0"). When starting up, 512 (2^9) telegram buffers are pre-allocated. The node database is configured to hold as many as 32 (2^5) nodes, including the current node. 128 (2^7) distributed message queues can be created on the local node. The local group database can hold up to 64 (2^6) groups, while the name database is limited to 256 (2^8) entries.
When the node bootstraps, it waits for 4 seconds (4*sysClkRateGet( )) to allow other nodes to respond.

NOTE

This routine is called automatically with default parameters when a target boots using a VxWorks image with VxFusion installed.

RETURNS

OK, or ERROR if the initialization fails.

distCtl( )

NAME

distCtl( ) - perform a distributed objects control function

SYNOPSIS

int distCtl
    (
    int function, /* function code */
    int argument  /* arbitrary argument */
    )

DESCRIPTION

This routine sets various parameters and hooks that control the system. It uses a syntax similar to that of the ioctl( ) routine. It accepts the following functions:
DIST_CTL_LOG_HOOK
This function sets a routine to be called each time a log message is produced. By default, the log hook writes the message to standard output. The prototype of the log( ) routine should look like this:
   void log (char *logMsg);
DIST_CTL_PANIC_HOOK
This function sets a routine to be called when the system panics. By default, the panic hook writes the panic message to standard output. The panic( ) routine must not return. The prototype of the panic( ) routine should look like this:
   void panic (char *panicMsg);
DIST_CTL_RETRY_TIMEOUT
This function sets the initial send retry timeout in clock ticks. If no ACK is received within a timeout period, the packet is resent. Although the retry timeout is set using clock ticks, the timeout period is rounded down to the nearest 500ms. The timeout period for the nth send is calculated as follows:

n * initial send retry timeout
*
DIST_CTL_MAX_RETRIES
This function sets a limit for the number of retries when sending fails.

DIST_CTL_NACK_SUPPORT
This function enables or disables the sending of negative acknowledgments (NACKs). NACKs are used to request a resend of a single missing fragment from a packet. They are sent immediately after a fragment is found to be missing. If arg is FALSE (0), the sending of negative acknowledgments is disabled. If arg is TRUE (1), the sending of NACKs is enabled. By default, NACKs are enabled.

DIST_CTL_PGGYBAK_UNICST_SUPPORT
This function enables or disables unicast piggy-backing. When unicast piggy-backing is enabled, the system waits at most 500ms until it sends an acknowledgment for a previously received packet. In the meantime, if a data packet is sent to a host already awaiting an acknowledgment, the acknowledgment is delivered with (that is, piggy-backed) the data packet. Enabling piggy-backing is useful for reducing the number of packets sent; however, it increases latency if no data packets are sent within the 500ms interval. When unicast piggy-backing is disabled, an acknowledgment is delivered immediately in its own packet. This function turns piggy-backing on and off for unicast communication only. If arg is FALSE (0), unicast piggy-backing is disabled. If arg is TRUE (1), unicast piggy-backing is enabled. By default, piggy-backing is disabled for unicast communication.

DIST_CTL_PGGYBAK_BRDCST_SUPPORT
This function enables or disables broadcast piggy-backing. When broadcast piggy-backing is enabled, the system waits at most 500ms until it sends an acknowledgment for a previously received packet. In the meantime, if a data packet is sent to a host already awaiting an acknowledgment, the acknowledgment is delivered with (that is, piggy-backed) the data packet. Enabling piggy-backing is useful for reducing the number of packets sent; however, it increases latency if no broadcast data packets are sent within the 500ms interval. When broadcast piggy-backing is disabled, an acknowledgment is delivered immediately in its own packet. This function turns piggy-backing on and off for broadcast communication only. If arg is FALSE (0), broadcast piggy-backing is disabled. If arg is TRUE (1), broadcast piggy-backing is enabled. By default, piggy-backing is disabled for broadcast communication.

DIST_CTL_OPERATIONAL_HOOK
This function adds a routine to a list of routines to be called each time a node shifts to the operational state. A maximum of 8 routines can be added to the list. The prototype of each operational( ) routine should look as follows:
   void operational (DIST_NODE_ID nodeStateChanged);
DIST_CTL_CRASHED_HOOK
This function adds a routine to a list of routines to be called each time a node shifts to the crashed state. A node shifts to the crashed state when it does not acknowledge a message within the maximum number of retries. The list can contain a maximum of 8 routines; however VxFusion supplies one routine, leaving room for only 7 user-supplied routines. The prototype of each crashed( ) routine should look as follows:
   void crashed (DIST_NODE_ID nodeStateChanged);
DIST_CTL_GET_LOCAL_ID
This function returns the local node ID.

DIST_CTL_GET_LOCAL_STATE
This function returns the state of the local node.

DIST_CTL_SERVICE_HOOK
This function sets a routine to be called each time a service fails, for a service invoked by a remote node. The argument parameter is a pointer to a servError( ) routine. The prototype of the servError( ) routine should look as follows:
   void servError (int servId, int status);
The system is aware of the following services:
DIST_ID_MSG_Q_SERV (0)     /* message queue service       */
DIST_ID_MSG_Q_GRP_SERV (1) /* message queue group service */
DIST_ID_DNDB_SERV (2)      /* distributed name database   */
DIST_ID_DGDB_SERV (3)      /* distributed group database  */
DIST_ID_INCO_SERV (4)      /* incorporation protocol      */
DIST_ID_GAP_SERV (5)       /* group agreement protocol    */
DIST_CTL_SERVICE_CONF
This function configures a specified service. The argument parameter is a pointer to DIST_SERV_CONF, which holds the service ID and its configuration to be set. DIST_SERV_CONF is defined as follows:
typedef struct
    {
    int servId;   /* ID of service to configure  */
    int taskPrio; /* priority of service task    */
    int netPrio;  /* network priority of service */
    } DIST_SERV_CONF;
The system is aware of the following services:
DIST_ID_MSG_Q_SERV (0)     /* message queue service       */
DIST_ID_MSG_Q_GRP_SERV (1) /* message queue group service */
DIST_ID_DNDB_SERV (2)      /* distributed name database   */
DIST_ID_DGDB_SERV (3)      /* distributed group database  */
DIST_ID_INCO_SERV (4)      /* incorporation protocol      */
DIST_ID_GAP_SERV (5)       /* group agreement protocol    */
If one of the configuration parameters is -1, it remains unchanged. The parameter taskPrio can range from 0 to 255; netPrio can range from 0 to 7.
A service's configuration can be changed at any time.

RETURNS

OK or the value requested if function is known; or ERROR if function is unknown or the argument is invalid.

ERRNO

S_distLib_UNKNOWN_REQUEST
The control function is unknown.

distLib

NAME

ROUTINES

DESCRIPTION

NOTE

INCLUDE FILES

SEE ALSO

distInit( )

NAME

SYNOPSIS

DESCRIPTION

EXAMPLE

NOTE

RETURNS

SEE ALSO

distCtl( )

NAME

SYNOPSIS

DESCRIPTION

RETURNS

ERRNO

SEE ALSO