Content-type: text/html
Manpage of MCL_CTL
MCL_CTL
Section: Misc. Reference Manual Pages (2)
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.
SEE ALSO
mcl_open(3),
MCL
documentation
AUTHORS
Vincent Roca (INRIA Rhone-Alpes, Planete project)
$Id: mcl_ctl.man.2,v 1.2 2003/10/27 09:55:47 roca Exp $
Index
- NAME
-
- SYNOPSIS
-
- DESCRIPTION
-
- RETURN VALUE
-
- EXAMPLE
-
- BUGS / LIMITATIONS
-
- COPYRIGHTS
-
- SEE ALSO
-
- AUTHORS
-
This document was created by
man2html,
using the manual pages.
Time: 13:49:41 GMT, November 26, 2003