Content-type: text/html Manpage of MCL_CTL

MCL_CTL

Section: Misc. Reference Manual Pages (3)
Updated:
Index Return to Main Contents

NAME

mcl_ctl - control function of the MultiCast Library (MCL)

SYNOPSIS

#include "../src/common/mcl_lib_api.h"

int mcl_ctl (int id, int optname, void* optvalue, int optlen);

DESCRIPTION

mcl_ctl is meant to control all the internal options of the MCL library and to offer the possibility to override default values. Most of these options only apply to the current session (identified by the id identifier).

The arguments are:

int id: session identifier returned by mcl_open
int optname: option name
void* optvalue: pointer to the value area. Depending on the option, this value can be provided to MCL (to set an option), or be modified and returned by MCL (to read the current value of an option).
int optlen: length of the value area.

The following options are defined:

MCL_OPT_LAYER_NB:

maximum number of layers used by a traffic source or a receiver (it depends on the congestion flow control module).

Argument: int

MCL_OPT_SINGLE_LAYER:

This argument optimizes transmissions for the single layer, fixed rate, no congestion-control case.

Argument: int (0 or 1)

MCL_OPT_PORT:

UDP port number in host order. Another way to specify the port number is to use MCL_OPT_BIND option.

Argument: int (and not a short!)

MCL_OPT_ADDR:

Another way to specify the address is to use MCL_OPT_BIND option. IPv4 address in host order.

Argument: int

MCL_OPT_BIND:

This is an alternative to the MCL_OPT_PORT and MCL_OPT_ADDR options. It's use is exactly the same as that of the Socket bind() system call. The struct sockaddr supplied is in network order (use hton functions first).

Argument: struct sockaddr

MCL_OPT_DEMUX_LABEL:

Specify the demultiplexing label to use on that session, also called Transport Session Identifier (TSI) in the ALC/LCT drafts.

Argument: int

MCL_OPT_TTL:

IP Time To Live (TTL) value. This parameters controls the scope of unicast and multicast packets generated by the traffic source. Use with care as large values of TTL can easily lead to flooding the whole MBONE.

Argument: int

MCL_OPT_STATS:

Controls the print of statistics during transmissions. A value of 0 will avoid any print (but statistics are anyway gathered), 1 will lead to print major statistics (e.g. at the end of reception), and 2 will lead to print statistics regularly.

Argument: int

MCL_OPT_VERBOSITY:

This option is only usefull if the MCL library has been compiled with the DEBUG flag. It controls the level of verbosity desired. It can range from 0 (quiet mode, the default), to 6 (full verbosity, with a message each time an MCL internal function is called). Usefull for debug and to know what's going on... A value of 2 is required to collect major events and do post analysis of a session using the tools in the "test" directory.

Argument: int

MCL_OPT_MOREABOUT:

Get release information, compilation flags and credits.

Argument: none

MCL_OPT_TMP_DIR:

Specify the directory to use for temporary files (e.g. for the virtual transmission memory service).

Argument: null terminated string (give the strlen() of this string in the optlen argument)

MCL_OPT_NETIF:

Network interface, in host order, to use. Only usefull in case of multi-homed hosts or routers.

Argument: int

MCL_OPT_LOOPBACK:

Should receivers on the same host as the source also receive data? (by default yes). Rarely usefull!

Argument: int

Source specific options:

MCL_OPT_DELIVERY_MODE:

Used by the traffic source (only) to specify the delivery mode. Currently, this mode can be DEL_MODE_PUSH for transmissions in ``push'' mode (i.e. data is sent once, all the receivers must be ready) and DEL_MODE_ON_DEMAND for transmissions in ``on-demand'' mode (i.e. data is sent continuously in cycles, receivers can arrive at any time, get data and leave).

Argument: int ( DEL_MODE_PUSH or DEL_MODE_ON_DEMAND )

MCL_OPT_TX_PROFILE:

Select a predefined transmission profile. Currently this profile can be one of MCL_TX_PROFILE_LOW_RATE_INTERNET , MCL_TX_PROFILE_MID_RATE_INTERNET , or MCL_TX_PROFILE_HIGH_SPEED_LAN . Several parameters are affected, like the number of layers, the transmission rate of the base layer (which also defines the transmission rate of all the upper layers), and the symbol size (with Internet communications 512 byte symbols are used to avoid any risk of fragmentation, on a LAN higher values are possible).

Argument: int

MCL_OPT_DATAGRAM_SIZE:

Datagram (i.e. symbol) size. Be carefull if a value superior to 512 bytes is used as IP datagram fragmentation (which is considered non efficient) may take place.

Argument: int

MCL_OPT_TX_RATE:

Transmission rate in symbols per second on the base layer (it must be an integral number). The transmission rate on all the upper layers are affected as they are multiples.

Argument: int

MCL_OPT_SET_FEC_CODE:

Specifies the FEC code to use from now on. Possible choices are currently: MCL_FEC_CODE_NULL, MCL_FEC_CODE_RSE, MCL_FEC_CODE_LDGM and MCL_FEC_CODE_LDPC. It is important that setting the FEC code takes place before selecting the FEC ratio, since this latter operates on the current FEC code, not all possible FEC codes. Only the sender needs to specify the FEC code to be used, the receiver will automatically switch to the appropriate decoder, taking into account the FEC information of the ALC/LCT header. Several FEC codes can be used simultaneously in the same ALC session, with an object granularity (i.e. all blocks of an object use the same FEC code).

Argument: int (one of the above MCL_FEC_CODE_XXX values)

MCL_OPT_FEC_RATIO:

Specifies the FEC ratio (a floating point number) to use. This ratio is given by total_nb_of_symbols / nb_of_data_symbols (or n / k), so a fec_ratio of 1.0 means no FEC at all, a fec_ratio of 2.0 means "as many FEC symbols as there are data symbols", etc. This ratio is the inverse of the ``code rate'' (following the official coding theory terminology).

Argument: float

MCL_OPT_REUSE_APPLI_TX_BUFFER:

Argument: int

MCL_OPT_VIRTUAL_TX_MEMORY:

Controls the virtual transmission memory service where data (and FEC) is stored on disk rather than in physical memory. The localization of the file can be controlled with the MCL_OPT_TMP_DIR option.

Argument: int (0 or 1)

MCL_OPT_KEEP_DATA:

Used in case of multiple objects to do symbol scheduling in a whole rather than independantly for each object. Works with the MCL_OPT_PUSH_DATA option. This option must be specified before the first object submission.

Argument: none

MCL_OPT_PUSH_DATA:

Used in case of multiple objects to do symbol scheduling in a whole rather than independantly for each object. Works with the MCL_OPT_KEEP_DATA option. This option must be specified after the submission of the last object.

Argument: none

MCL_OPT_SCHED:

Specifies the symbol scheduler (i.e. what symbols to send on what layer) to use. Currently one can choose either MCL_SCHED_LCT1 (send the same symbols on each layer) or MCL_SCHED_LCT2 (send data on the base layer, a first set of FEC symbols on layer 1, a second set of FEC symbols on layer 2, etc.), or MCL_SCHED_LCT3 (similar to version 2 but dedicated to huge objects).

Argument: int

MCL_OPT_OBJ_SCHED

Specifies the object scheduler (i.e. with multiple objects in what order should the objects be scheduled on the various layers). Currently one can choose MCL_SCHED_SEQUENTIAL_OBJ_ORDER , MCL_SCHED_RANDOM_OBJ_ORDER , MCL_SCHED_PARTIALLY_MIXED_ORDER , or MCL_SCHED_MIXED_ORDER.

Argument: int

Receiver specific options:

MCL_OPT_IMMEDIATE_DELIVERY:

In case of multi-object session, do you want that an object be delivered to the application as soon as it has been completely received or not? If enabled, then objects may be delivered out of order...

Argument: int (0 or 1)

MCL_OPT_POSTPONE_FEC_DECODING:

Do not decode FEC symbols immediately but wait until enough symbols have been received for each block to start decoding. Highly recommended with slow FEC codecs (like the Reed-Solomon codec) and high speed reception rates.

Argument: int

MCL_OPT_SEQNB_STATS:

(deprecated)

Argument: int

MCL_OPT_NEVER_LEAVE_BASE_LAYER:

The library will not try to leave the base layer after the successfull decoding of all objects. This is required by the MCL_WAIT_EVENT_CLOSED event (see mcl_wait_event(2) manual). Note that even without this option, even in front of losses, a receiver is guaranted not to leave the base layer during symbol transfer.

Argument: int (0 (default) or 1)

See the file "src/mcl_lib.h" and the MCL documentation for additional information.

RETURN VALUE

On success returns 0, on error a non-zero value.

EXAMPLE

Here is a simple example.

        int     port = 2324;    /* in host format! */
        int     err = 0;

        if (err = mcl_ctl(id, MCL_OPT_PORT, (void*)&port, sizeof(port))) {
                printf("error, mcl_ctl failed\n");
                exit(1);
        }

BUGS / LIMITATIONS

The session cannot be fully initialized (in particular the subscription to all multicast groups) before we are sure that all control parameters have been negociated with the various mcl_ctl() calls. By convention, the MCL library assumes that once an mcl_send(to) or mcl_recv(from) call is issued, all the principal control parameters have been issued and the session initialization can be finished. It means that packets destinated to the target multicast groups before a receiver has issued the first mcl_recv(from) will all be lost, even if the multicast group/port number have been specified. To avoid it, mcl_recv(from) can be called with a null buffer and/or a nul buffer len just after the specification of the target multicast group and port number (and demux label if any).

COPYRIGHTS

Copyright (c) 1999-2003 INRIA - Universite Paris 6 -
All rights reserved
(main author: Vincent Roca - vincent.roca@inrialpes.fr)

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

AUTHORS

Vincent Roca (INRIA Rhone-Alpes, Planete project)

$Id: mcl_ctl.man.3,v 1.2 2003/11/28 10:05:31 roca Exp $

This document was created by man2html, using the manual pages.
Time: 16:28:10 GMT, December 21, 2004

MCL_CTL

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

EXAMPLE

BUGS / LIMITATIONS

COPYRIGHTS

SEE ALSO

AUTHORS

Index