rpc_server_listen(3rpc)
Tells the RPC runtime to listen for remote procedure calls
Used by server applications.
Synopsis
#include <dce/rpc.h>
void rpc_server_listen(
unsigned32 max_calls_exec,
unsigned32 *status);
Parameters
Input
max_calls_exec
Specifies the maximum number of concurrent executing remote procedure calls.
Use the value rpc_c_listen_max_calls_default to specify the default value.
Also, the five rpc_server_use_*protseq* routines limit (according to their max_call_requests parameter) the number of concurrent remote procedure call requests that a server can accept.
Output
status
Returns the status code from this routine. This status code indicates whether the routine completed successfully or, if not, why not.
Description
The rpc_server_listen( ) routine makes a server listen for remote procedure calls. DCE RPC allows a server to simultaneously process multiple calls. The
max_calls_exec parameter specifies the maximum number of concurrent remote procedure calls the server executes. Each remote procedure call executes in a call execution thread. The
implementation of the RPC architecture determines whether it reuses call execution threads for the execution of subsequent remote procedure calls or, instead, it creates a new thread for each
execution of a subsequent remote procedure call. The following conditions affect the number of concurrent remote procedure calls that a server can process:
· Sufficient network resources must be available to accept simultaneous call requests arriving over a particular protocol sequence. The value of max_call_requests in the five rpc_server_use_*protseq* routines advises the RPC runtime about the runtime's request of network resources.
· Enough call threads must be available to execute the simultaneous call requests once they have been accepted. The value of max_calls_exec in rpc_server_listen( ) specifies the number of call threads.
These conditions are independent of each other.
A server application that specifies a value for max_calls_exec greater than 1 is responsible for concurrency control among the remote procedures since each executes in a separate thread.
If the server receives more remote procedure calls than it can execute (more calls than the value of max_calls_exec), the RPC runtime accepts and queues additional remote procedure calls until a call execution thread is available. From the client's perspective, a queued remote procedure call appears the same as one that the server is actively executing. A client call remains blocked and in the queue until any one of the following events occurs:
· The remote procedure call is assigned to an available call execution thread and the call runs to completion.
· The client no longer can communicate with the server.
· The client thread is canceled and the remote procedure call does not complete within the cancel time-out limits.
The implementation of the RPC architecture determines the amount of queuing it provides. The RPC runtime continues listening for remote procedure calls (that is, the routine does not return to the server) until one of the following events occurs:
· One of the server application's manager routines calls rpc_mgmt_stop_server_listening( ).
· A client is allowed to, and makes, a remote rpc_mgmt_stop_server_listening( ) call to the server.
On receiving a request to stop listening, the RPC runtime stops accepting new remote procedure calls for all registered interfaces. Executing calls and existing queued calls are allowed to complete.
After all calls complete, rpc_server_listen( ) returns to the caller, which is a server application.
For more information about a server's listening for and handling incoming remote procedure calls, refer to the OSF DCE Application Development Guide - Core Components. It also contains information about canceled threads.
Return Values
No value is returned.
Errors
The following describes a partial list of errors that might be returned. Refer to the OSF DCE Problem Determination Guide for complete descriptions of all error messages.
rpc_s_ok
Success.
rpc_s_already_listening
Server already listening.
rpc_s_max_calls_too_small
Maximum calls value too small.
rpc_s_no_protseqs_registered
No protocol sequences registered.
Related Information
Functions: rpc_mgmt_stop_server_listening(3rpc)
rpc_server_use_all_protseqs(3rpc)
rpc_server_use_all_protseqs_if(3rpc)
rpc_server_use_protseq_ep(3rpc)
rpc_server_use_protseq_if(3rpc)
Books: OSF DCE Application Development Guide - Core Components