Just trying to make this whole manual make more sense.
[charm.git] / doc / converse / ldb.tex
1 \chapter{Load Balancer}
2
3 Converse provides the programmer with a number of Load Balancing
4 strategies in order to distribute work among the processors in the
5 system. The load balancing strategy to be used in the program can be
6 specified at the link time. \note{In the future versions, we will
7 provide the users with ability to write their own load balancing
8 strategies. However, in this version, the choice is limited to certain
9 predefined load balancing strategies.} Following functions are provided
10 for interfacing the converse program with the load balancing module of
11 Converse.
12
13 \function{void CldNewSeedFromLocal(void *msg, void *ldb, void (*sendfn)(),int queueing, int priolen, int *prioptr)}
14 \index{CldNewSeedFromLocal}
15 \desc{Hand over the message \param{msg}, which is freshly generated by
16 the local processor, to the load balancing module. This load balancing
17 module may use the space provided by \param{ldb} to either send the
18 message off to other processors using \param{sendfn()}, or may decide
19 to enqueue it locally using the queuing strategy \param{queueing} and
20 priority specifiers \param{priolen} and \param{prioptr}.}
21
22 \function{void CldNewSeedFromNet(void *msg, void *ldb, void (*sendfn)(),int queueing, int priolen, int *prioptr)}
23 \index{CldNewSeedFromNet}
24 \desc{Hand over the message \param{msg}, which is received from
25 network, to the load balancing module. This load balancing
26 module may use the space provided by \param{ldb} to either send the
27 message off to other processors using \param{sendfn()}, or may decide
28 to enqueue it locally using the queuing strategy \param{queueing} and
29 priority specifiers \param{priolen} and \param{prioptr}.}
30
31
32 The rationale behind this interface is as follows: A typical load
33 balancing strategy can have different behaviors based on whether the
34 message (\param{msg}) specifying work to be done is freshly generated
35 by the local processor or has arrived from the network after one or
36 more hops from the generating processor to local processor.
37 \note{Message \param{msg} must have its handler field set before it is
38 handed over to the load balancing module.} If the work is freshly
39 issued, one hands it over to the load balancing module using function
40 \param{CldNewSeedFromLocal()} otherwise calls
41 \param{CldNewSeedFromNet()}. Each load balancing strategy may have
42 different use of the parameter \param{ldb}. Some of the currently
43 implemented language specific load balancing strategies use this area
44 in the message for sending the load information on local processor
45 piggy-backed onto the message periodically; some of them may not need
46 this area at all. \note{The only ldb strategy available to converse
47 users currently, i.e. random, does not use this area and the user could
48 specify \param{void * (0))} there.}
49
50 Some of the parallel languages or libraries built on top of converse
51 may have the message packing mechanisms which have to be called before
52 any message crosses address boundaries. Therefore the load balancing
53 module cannot use the built-in function such as \param{CmiAsyncSend()}
54 for sending the work off to another processor. For this reason, the
55 user needs to specify a function \param{sendfn()} which takes two
56 parameters:  \param{void *msgptr} and \param{int destPE}. Languages or
57 runtimes using packing can pack the message before sending it to
58 processor \param{destPE} in \param{sendfn()}. However, if the load
59 balancing module decides not to send \param{msg} to any other
60 processor, it may queue it to the processors local queue. For this
61 eventuality, one has to specify the queuing parameters in above calls.
62 They are:  \param{queuing}--a queuing strategy (see
63 \param{CsdEnqueueGeneral())}; \param{priolen}--length of the priority
64 field; and \param{prioptr}--pointer to the priority information. If the
65 user is not using priorities, \param{priolen} should be 0.
66
67 \internal{
68 \function{void CldFillLdb(int destPE, void *ldb)}
69 \index{CldFillLdb}
70 \desc{}
71
72 \function{CldStripLdb(void *ldb)}
73 \index{CldStripLdb}
74 \desc{}
75 }
76
77 %\internal{
78 %\function {void ClbInit(void)}
79 %Routine called at scheduler startup to allow the load balancer to
80 %register its own message handlers.
81 %}
82 %
83 %\function {void ClbEnqueue(Message *msg, FunctionPtr send\_func)}
84 %Function called by a handler to let the load balancer know about a
85 %``seed'' message. If the seed is to be processed locally, the
86 %load balancer will
87 %enqueue it in the scheduler's queue to be eventually executed.
88 %{\sf send\_func} specifies the function
89 %which should be used to send the seed to another processor
90 %if it is not to be processed locally.
91 %
92 %\function {void ClbEnqueuePrio(Message *msg, FunctionPtr send\_func,
93 %void *prio, int len)} 
94 %Same as {\sf ClbEnqueue()}, except that a priority {\sf prio} of length
95 %{\sf len} bytes is associated with the message.
96 %
97 %
98 %The most general load balancing scheme will have three opportunities
99 %to migrate load.  The first will be when {\sf ClbEnQueue()} is called.
100 %This routine will either immediately send the message elsewhere for
101 %processing, or enqueue it in a local data structure.  A token message
102 %will then be enqueued with the scheduler to reactivate the load
103 %balancing in order to execute the seed message at the appropriate
104 %time.  The second opportunity for load balancing occurs when the load
105 %balancing module receives a request from the load balancing module on
106 %another processor for some work.  When this occurs, a message will be
107 %delivered to the requesting node from the load balance queue, and the
108 %token message in the scheduler queue will be marked as invalid.  The
109 %third opportunity occurs when a token message is removed from the
110 %scheduler queue.  Control will return to the load balancing module,
111 %which could then choose to send seed messages to another host.
112