DMNET(3dm)DMNET(3dm)NAME
dmNet, dmNetIntro - Digital Media Network Library
SYNOPSIS
#include <dmedia/dmnet.h>
-ldmnet
DMnetconnection cnp;
DESCRIPTION
dmNet Library is used by applications that need to transfer DMbuffers
between processes on the same host, or on different hosts across a
network.
dmNet performs marshalling and unmarshalling of DMbuffers, converting
timestamps and endianness. dmNet abstracts the underlying transport, and
provides maximal throughput across network transports like Ethernet,
Striped Hippi and Fibrechannel, by using native protocols whenever
possible, thus liberating applications from the task of network-specific
performance optimizations. dmNet also provides a low overhead local path
for inter-process communication.
dmNet is built upon a plugin architecture, allowing for extensible
support of new transports by downloading plugins.
PROGRAMMING MODEL
dmNet uses a handle of type DMnetconnection to keep track of state
associated with the dmnet connection. The library calls exported by dmnet
are are modelled on BSD socket calls. dmNet supports unidirectional flow
of DMbuffers; thus two connections must be made for bidirectional flow.
PROGRAMMING INTERFACE
Some calls are specific to sender or receiver, and are noted as such.
All calls return DM_SUCCESS or DM_FAILURE. If DM_FAILURE is returned, a
call to dmGetError(3dm) may be made to determine the cause of failure.
dmNetOpen(3dm), dmNetClose(3dm) - initialize and close the handle, common
to sender and receiver.
dmNetListen(3dm), dmNetAccept(3dm) - receiver calls, must be called
before dmNetConnect is called by sender. dmNetAccept blocks until
dmNetConnect is called by sender. If dmNetListen fails with EADDRINUSE, a
new port should be negotiated by the server and client.
dmNetConnect(3dm) - sender call, must be called before dmNetAccept is
called by receiver.
dmNetSend(3dm) - sender call, sends a DMbuffer.
Page 1
DMNET(3dm)DMNET(3dm)dmNetRecv(3dm) - receiver call, receives a DMbuffer.
dmNetRegisterPool(3dm), dmNetRegisterBuffer(3dm) - registers a
DMbufferpool, or a single DMbuffer with dmNet. When dmNetRecv is called,
a DMbuffer is allocated from the pool, or a preallocated DMbuffer is used
to store the incoming DMbuffer. Registration needs to be done only by the
receiver. dmNetRegisterBuffer indicates to dmNet that a preallocated
DMbuffer is being passed into dmNetRecv.
dmNetQueryHardware(3dm), dmNetQueryProtocol(3dm),
dmNetSelectProtocol(3dm) - querying calls, used in conjunction with the
configuration file /var/dmedia/dmnet/dmnet.conf. dmNetQueryHardware
returns all network devices on the host; dmNetQueryProtocol returns all
protocols supported by a particular network device; and
dmNetSelectProtocol fills a DMparams structure with parameters necessary
for dmNet to use a particular device and protocol. The configuration file
contains lines of name=value pairs, and each line contains all the
parameters and their values for a particular hardware and protocol. This
frees application from having to set connection parameters explicitly,
and allows it to present users with a choice of all hardware and protocol
options available on the machine. The configuration file must be updated
manually by a system adminstrator.
dmNetGetParams(3dm) - called before the DMbufferpool is allocated so
dmNet may modify or add parameters to the parameter list.
dmNetDataFd(3dm) - returns a file descriptor that can be used with
select, for non-blocking behaviour.
EXAMPLE
More complete examples are available in /usr/share/src/dmedia/dmnet. The
following code fragment does not check return values, and is meant for
illustration only. It sends or receives a single DMbuffer over tcp/ip,
based on the flag "receiver".
DMnetconnection cnp;
DMbuffer dmbuf;
DMparams* plist;
short port=5555;
dmNetOpen(&cnp);
dmParamsCreate(&plist);
dmParamsSetInt(plist, DMNET_PORT, port);
if (receiver) {
dmNetListen(cnp, plist);
dmNetAccept(cnp, plist);
} else {
dmParamsSetString(plist, DMNET_REMOTE_HOSTNAME, "foo.sgi.com");
dmNetConnect(cnp, plist);
}
dmBufferSetPoolDefaults(plist, POOLSIZE, BUFFERSIZE, DM_TRUE, DM_FALSE);
Page 2
DMNET(3dm)DMNET(3dm)
dmNetGetParams(cnp, plist);
dmBufferCreatePool(plist, &pool);
dmNetRegisterPool(cnp, pool);
if (receiver) {
dmNetRecv(cnp, &dmbuf);
/* do cool stuff with the buffer we've received */
} else {
dmBufferAllocate(pool, &dmbuf);
/* fill the dmbuf with data */
dmNetSend(cnp, dmbuf);
}
dmBufferFree(dmbuf);
dmNetClose(cnp);
PARAMETERS
DMNET_CONNECTION_TYPE specifies the transport to use, and is one of
DMNET_LOCAL, DMNET_TCP, DMNET_STRIPED_HIPPI, DMNET_PLUGIN (default is
DMNET_TCP). DMNET_LOCAL is the fast local case, when DMbuffers are
transferred between processes.
DMNET_TCP works over all networks that implement TCP/IP, including
Ethernet, Hippi, Fibrechannel, ATM, etc. Note that TCP will not yield the
best performance in the general case, so native protocols are supported
for maximum throughput (wire speeds for most configurations) over Hippi
and Fibrechannel.
DMNET_STRIPED_HIPPI uses the native Hippi Framing Protocol, also referred
to as the character driver interface. The sender and receiver open Hippi
devices, like /dev/hippi0, for instance, perform a few ioctls, and make
read and write calls. Thus the hippi device(s) must be specified to dmNet
through parameters DMNET_HIPPI_DEV#, where # is 0, 1, 2,..,n, where n is
specified by DMNET_HIPPI_NDEV. When multiple hippi devices are specified,
data is striped across all specified devices with almost a linear
increase in throughput with number of devices (a single fibre should
yield over 80 MB/sec of throughput). So for example, if the host has
active hippi devices /dev/hippi3 and /dev/hippi5, you would set
DMNET_HIPPI_NDEV to 2, DMNET_HIPPI_DEV0 to "/dev/hippi3" and
DMNET_HIPPI_DEV1 to "/dev/hippi5". netstat -i reveals all active hippi
devices. The example code in /usr/share/src/dmedia/dmnet/ demonstrates
how this may be done in more detail. Note that striping is possible
because of multiple threads, and sproc is called from within dmNet when
this connection type is set. Hippi works best with very large buffers, in
the order of MBytes. Small buffer transfers will not give high
throughput.
DMNET_PLUGIN specifies that a plugin will be used, and DMNET_PLUGIN_NAME
indicates the name of the plugin. dmNet is based on a plugin
architecture, which means that plugins are available for download that
support new interfaces. The Fibrechannel Transporter interface is an
Page 3
DMNET(3dm)DMNET(3dm)
example of a network transport that is supported through plugins. Hippi
is another example, though hippi is also integrated with the dmNet core.
The plugins are usually located in /usr/lib32/dmedia/plugins/dmnet/.
Plugins may require additional parameters, and these are specified in
their header files, located at /usr/include/dmnet/. Fibrechannel
transporter, for example, requires the specification of
DMNET_TRANSPORTER_REMOTE_HOSTNAME. DMNET_PORT is the port agreed upon by
the sender and receiver. This must be specified, even if the data
transport is not tcp, because there is always some control tcp traffic.
Note that this means that there must always be a tcp path between hosts
using dmNet. Port negotiation is assumed to take place by external means,
such as through an independant network connection, or with a well known
port, etc. If dmNetListen fails with EADDRINUSE, the port specified is
being used, and another one must be chosen.
DMNET_REMOTE_HOSTNAME must be specified before dmNetConnect can be called
(unless DMNET_REMOTE_SOCKADDR is specified). The hostname must be the
address of a network interface that supports tcp/ip.
DMNET_REMOTE_SOCKADDR , DMNET_LOCAL_SOCKADDR These are optional and
provide a way for the application to specify a socket address.
DMNET_REMOTE_SOCKADDR is specified before dmNetConnet, and
DMNET_LOCAL_SOCKADDR is specified before dmNetAccept. If
DMNET_REMOTE_HOSTNAME is specified, DMNET_REMOTE_SOCKADDR is ignored.
DMNET_LOCAL_SOCKADDR may be used to specify the interface to bind to if
the host has multiple interfaces.
FILES
/usr/lib32/libdmnet.so dmNet DSO
/usr/include/dmedia/dmnet.h dmNet call prototypes
/usr/include/dmedia/dmnet_params.h dmNet param defns
/usr/include/dmnet/ header files for plugins
/usr/lib32/dmedia/plugins/dmnet/ plugin DSOs
/var/dmedia/dmnet/dmnet.conf configuration file for querying
SEE ALSOdmNetOpen(3dm), dmNetClose(3dm), dmNetListen(3dm), dmNetAccept(3dm),
dmNetConnect(3dm), dmNetSend(3dm), dmNetRecv(3dm),
dmNetQueryHardware(3dm), dmNetQueryProtocol(3dm),
dmNetSelectProtocol(3dm), dmNetRegisterPool(3dm),
dmNetRegisterBuffer(3dm), dmNetGetParams(3dm), dmNetDataFd(3dm),
DMbuffer(3dm), vlintro(3dm)
Page 4
