station_8h-source.html

用来介绍ZIG Library游戏网络引擎的文档

00286         <span class="comment">// "cancel flag": if non-zero, a volatile bool variable that when set to true by another thread,</span>
00287         <span class="comment">// causes the request to give up immediately.</span>
00288         <a class="code" href="classbuffer__c.html">buffer_c</a> make_request(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;req, <span class="keywordtype">int</span> timeout_ms, <span class="keyword">volatile</span> <span class="keywordtype">bool</span> *cancel_flag, <span class="keywordtype">int</span> interval_ms = 200, <span class="keywordtype">int</span> send_ms = -1) {
00289                 <span class="keywordflow">return</span> do_make_request(<span class="keyword">false</span>, req, timeout_ms, cancel_flag, interval_ms, send_ms);
00290         }
00291 
00292         <span class="comment">// sends a response to an incoming request. requests come through receive_packet().</span>
00293         <span class="comment">// returns result of nlWrite().</span>
00294         <span class="comment">// after you answer a given request_id, you will not receive the same request again; the station</span>
00295         <span class="comment">// will re-send the answer you give here as many times as needed.</span>
00296         <span class="keywordtype">int</span> answer_request(<span class="keywordtype">int</span> request_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;response) {
00297                 <span class="keywordflow">return</span> do_answer_request(<span class="keyword">false</span>, request_id, response);
00298         }
00299 
00300         <span class="comment">// ===== TCP CHANNELS API ===============================================</span>
00301         <span class="comment">// trying a new design: now the "channels" stuff is included in the "station" object.</span>
00302         <span class="comment">// a TCP channel is opened using a connected UDP station (make_request())</span>
00303         <span class="comment">// ======================================================================</span>
00304 
00305         <span class="comment">// set the channel callback interface. this interface is notified of channel events.</span>
00306         <span class="comment">// "tag" is an integer that will be passed as parameter to all callbacks (this is</span>
00307         <span class="comment">// for the "client id" when the station is used by the server)</span>
00308         <span class="keywordtype">void</span> set_callback_interface(station_callback_i *beh, <span class="keywordtype">int</span> tag) { this-&gt;beh = beh; channel_tag = tag; }
00309 
00310         <span class="comment">// start a thread to open a new TCP channel. station must be connected already.</span>
00311         <span class="comment">// returns 0 if the station is not connected or already disconnecting.</span>
00312         <span class="comment">// returns the ID of the channel if successful.</span>
00313         <span class="comment">// (REVIEW: must have a mutex around a "disconnecting flag" - atomic counter)</span>
00314         <span class="comment">// result comes in the callback interface.</span>
00315         <span class="comment">//</span>
00316         <span class="comment">//   IMPORTANT: only one of the two connected stations can start opening</span>
00317         <span class="comment">//     channels. if you try to open in both sides, duplicate channel_ids will be</span>
00318         <span class="comment">//     generated. restrict opening channels in the side of the connection that</span>
00319         <span class="comment">//     plays the role of the "server", for instance.</span>
00320         <span class="comment">//</span>
00321         <span class="comment">//   tcp_listen_port : since TCP listening is dealt with outside the station, must</span>
00322         <span class="comment">//     tell what's the port we're listening in. if 0, not listening.</span>
00323         <span class="comment">//</span>
00324         <span class="keywordtype">int</span> open_channel();
00325 
00326         <span class="comment">// channel write. returns result of nlWrite.</span>
00327         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00328         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLubyte out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00329         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLbyte out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00330         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLushort out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00331         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLshort out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00332         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLulong out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00333         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLlong out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00334         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLfloat out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00335         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, NLdouble out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00336         <span class="keywordtype">int</span> chan_write(<span class="keywordtype">int</span> channel_id, std::string out, <span class="keywordtype">bool</span> timeout_is_failure = <span class="keyword">true</span>, <span class="keywordtype">double</span> timeout = 3.0);
00337 
00338         <span class="comment">// close a channel. needed - you could close a channel by quitting the listener,</span>
00339         <span class="comment">// but the listener may be stuck in a blocking read() operation. returns 1 if successful</span>
00340         <span class="comment">// or 0 if failed.</span>
00341         <span class="comment">// this DOES NOT delete the channel or take it out from the map because the only thread</span>
00342         <span class="comment">// that can do this is the listener thread!</span>
00343         <span class="keywordtype">int</span> close_channel(<span class="keywordtype">int</span> channel_id);
00344 
00345         <span class="comment">// TCP listen socket: incoming TCP connection</span>
00346         <span class="comment">// this must be called by the user. the station doesn't implement TCP socket listening.</span>
00347         <span class="comment">// this method tells the station: this socket is a connected TCP blocking socket to the</span>
00348         <span class="comment">// other station to which you are already connected.</span>
00349         <span class="comment">// channel id, etc. is read from the channel, so no additional details are needed.</span>
00350         <span class="keywordtype">void</span> incoming_channel_socket(NLsocket sock);
00351         
00352 <span class="keyword">protected</span>:
00353 
00354         <span class="comment">//make an internal or user request</span>
00355         <a class="code" href="classbuffer__c.html">buffer_c</a> do_make_request(<span class="keywordtype">bool</span> is_internal, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;req, <span class="keywordtype">int</span> timeout_ms, <span class="keyword">volatile</span> <span class="keywordtype">bool</span> *cancel_flag, <span class="keywordtype">int</span> interval_ms = 200, <span class="keywordtype">int</span> send_ms = -1);
00356 
00357         <span class="comment">//make an internal request</span>
00358         <a class="code" href="classbuffer__c.html">buffer_c</a> make_internal_request(<a class="code" href="classbuffer__c.html">buffer_c</a> &amp;req, <span class="keywordtype">int</span> timeout_ms, <span class="keyword">volatile</span> <span class="keywordtype">bool</span> *cancel_flag, <span class="keywordtype">int</span> interval_ms = 200, <span class="keywordtype">int</span> send_ms = -1) {
00359                 <span class="keywordflow">return</span> do_make_request(<span class="keyword">true</span>, req, timeout_ms, cancel_flag, interval_ms, send_ms);
00360         }
00361 
00362         <span class="comment">//answer an internal or user request</span>
00363         <span class="keywordtype">int</span> do_answer_request(<span class="keywordtype">bool</span> is_internal, <span class="keywordtype">int</span> request_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;response);
00364 
00365         <span class="comment">//answer an internal request</span>
00366         <span class="keywordtype">int</span> answer_internal_request(<span class="keywordtype">int</span> request_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;response) {
00367                 <span class="keywordflow">return</span> do_answer_request(<span class="keyword">true</span>, request_id, response);
00368         }       
00369 
00370         <span class="comment">//station's internal request handler</span>
00371         <span class="keywordtype">void</span> incoming_internal_request(<span class="keywordtype">int</span> request_id, <a class="code" href="classbuffer__c.html">buffer_c</a> &amp;request);
00372 
00373         <span class="comment">//thread callback to run "channel opened" on the station_callback_i (beh)</span>
00374         <span class="keywordtype">void</span> *channel_thread_run(<span class="keywordtype">void</span> *arg);
00375 
00376         <span class="comment">//reset state</span>
00377         <span class="keywordtype">void</span> reset_state();
00378 
00379         <span class="comment">//process message that arrived</span>
00380         <span class="keywordtype">void</span> process_incoming_message(NLushort msgid, <span class="keywordtype">int</span> msgsize, <a class="code" href="classbuffer__c.html">buffer_c</a> *in);
00381 
00382         <span class="comment">//search for old answers in answs and remove them</span>
00383         <span class="keywordtype">void</span> remove_old_answers();
00384 
00385         <span class="comment">// incoming channel connection for a master</span>
00386         <span class="keywordtype">void</span> master_incoming_channel_connection(<span class="keywordtype">int</span> channel_id, NLsocket sock);
00387 
00388         <span class="comment">// incoming channel connection for a slave</span>
00389         <span class="keywordtype">void</span> slave_incoming_channel_connection(<span class="keywordtype">int</span> channel_id, NLsocket sock);
00390 
00391         <span class="comment">// method for running the "open_channel()" thread (master's)</span>
00392         <span class="keywordtype">void</span> *open_channel_thread_run(<span class="keywordtype">void</span> *arg);
00393 
00394         <span class="comment">// called from open_channel_thread_run()</span>
00395         <span class="keywordtype">int</span> do_open_channel_thread_run(<span class="keywordtype">int</span> channel_id);
00396 
00397         <span class="comment">// thread that connects to a TCP listening socket</span>
00398         <span class="keywordtype">void</span> *tcp_connect_thread_run(<span class="keywordtype">void</span> *arg);
00399 
00400         <span class="comment">// channel thread finalization (common part)</span>
00401         <span class="keywordtype">void</span> channel_thread_finalization(<span class="keywordtype">int</span> channel_id);
00402 
00403 <span class="comment">//---- MEMBER VARS -------------------------------------------------------</span>
00404 
00405         <span class="comment">//debug string (id)</span>
00406         <span class="keywordtype">char</span> dstr[64];
00407 
00408         <span class="comment">//callback interface</span>
00409         station_callback_i *beh;
00410 
00411         <span class="comment">//debug console</span>
00412         <a class="code" href="classconsole__c.html">console_c</a>       *con;
00413 
00414         <span class="comment">//flag for assertion</span>
00415         <span class="comment">//"station closing or already closed" flag, so we can't open more channels.</span>
00416         atomic_c&lt;bool&gt; opened;
00417 
00418         <span class="comment">//"volatile bool" version of "opened". when opened == false, quitting_flag == true</span>
00419         <span class="comment">// this is for the make_internal_request() when opening channels</span>
00420         <span class="keyword">volatile</span> <span class="keywordtype">bool</span> opened_is_false;
00421 
00422         <span class="comment">//temporary buffer for nlRead, first stage (data may be compressed, or not)</span>
00423         <span class="comment">//char udp_buf_zipped[ZIG_ULTIMATE_UDP_PACKET_SIZE_LIMIT];</span>
00424         <span class="comment">//NEW (v1.3.0): eliminate memory wastage and need for the fixed size</span>
00425         <a class="code" href="classbuffer__c.html">buffer_c</a>        udp_buf_zipped_b;
00426 
00427         <span class="comment">//temporary buffer for nlRead, for when udp_buf_zipped contained compressed data</span>
00428         <span class="comment">//char udp_buf_unzipped[ZIG_ULTIMATE_UDP_PACKET_SIZE_LIMIT];            </span>
00429         <span class="comment">//NEW (v1.3.0): eliminate memory wastage and need for the fixed size</span>
00430         <a class="code" href="classbuffer__c.html">buffer_c</a>        udp_buf_unzipped_b;