diff --git a/doc/Protocol-A.texi b/doc/Protocol-A.texi index 3c104ac794a13109185d3f7d051fb202ad2cf001..349bbbd6cc22ef2066d4296b261fab61a9b504c6 100644 --- a/doc/Protocol-A.texi +++ b/doc/Protocol-A.texi @@ -2711,6 +2711,7 @@ at the user's machine or ``unknown'' if Ident was not used. @tindex Static-Session-Info @tindex Session-Flags @tindex Dynamic-Session-Info +@tindex Scheduling-Info @example Session-Info ::= ( person : @lt{Pers-No}; @@ -2764,6 +2765,12 @@ at the user's machine or ``unknown'' if Ident was not used. flags : @lt{Session-Flags}; what-am-i-doing : @lt{HOLLERITH}; ) + +@anchor{Scheduling-Info} + Scheduling-Info ::= + ( priority : @lt{INT16}; + weight : @lt{INT16}; + ) @end example These data types give information about a particular LysKOM session. The @@ -2879,6 +2886,27 @@ The dynamic session flags (see above.) What the client is doing. This string is set by the client. @end table +The @type{Scheduling-Info} type determines how the resources are +shared between different sessions@footnote{RFC 2782 (DNS SRV) provided +inspiration when the @type{Scheduling-Info} structure was defined.}. +See @reqlink{get-scheduling} and @reqlink{set-scheduling} for more +information. It contains these fields: + +@table @field +@item priority +Clients with a numerically lower @field{priority} value will have +priority over other clients. A client with @field{priority} set to 0 +can totally starve clients with @field{priority} set to 1, 2 or +anything higher. + +@item weight +Within a priority class, the resources are shared in proportion to the +@field{weight} value. If one client has a weight of 200 and another of +50, the first client will get roughly four times as much work done +(assuming that the server is the limiting factor). + +@end table + @node Statistics @section Statistics @@ -2919,9 +2947,9 @@ When calculating the @field{ascent-rate}, only events that cause the value to increase are considered. Likewise, the @field{descent-rate} only considers events that decrease the value. -Example: if the measurment period is 60 seconds, the value starts at +Example: if the measurement period is 60 seconds, the value starts at 5, and it is increased by one 90 times and decreased by one 60 times -during the measurment period, the value will of course be 35 when the +during the measurement period, the value will of course be 35 when the period ends. The ascent rate will be 1.5 per second, and the descent rate 1.0 per second. @@ -3066,7 +3094,7 @@ their current status. * set-membership-type:: r Modify the type of conference (102) * local-to-global:: r Map local text numbers to global ones (103) * map-created-texts:: r Map texts created by a person to global (104) -* set-keep-commented:: e Set how new comments protect old texts (105) +* set-keep-commented:: r Set how new comments protect old texts (105) * set-pers-flags:: r Set personal flags (106) * query-read-texts:: r Get info on what is read (107) * get-membership:: r Get membership for a person (108) @@ -3079,6 +3107,8 @@ their current status. * first-unused-text-no:: r Get first unused text number (115) * find-next-conf-no:: r Get next conference number (116) * find-previous-conf-no:: r Get previous conference number (117) +* get-scheduling:: e Get client priority information (118) +* set-scheduling:: e Alter client priority (119) @end menu @ifnottex @@ -7923,7 +7953,7 @@ information about the texts in the conference. @end table @node set-keep-commented -@section set-keep-commented [105] (10) Experimental +@section set-keep-commented [105] (10) Recommended @findex set-keep-commented @example @@ -8284,8 +8314,9 @@ the previous range. The @field{error-status} indicates the interval @end example Return a list of the supported statistical measurements. This request -always succeeds, but it might return additional values if you are -logged in or if you have enough privileges. +always succeeds, and always returns the same value for the duration of +a session, so a client doesn't need to use it more than once per +session. @xref{Stats-Description}, for more info about the data type. @xref{Measured Properties}, for more info on what the returned values @@ -8343,7 +8374,10 @@ The measurement that was requested has been disabled. The server doesn't measure the value requested by @rarg{what}. @item access-denied -The client isn't allowed to retrieve the requested value. +The client isn't allowed to retrieve the requested value. The client +might be granted the privilege by logging in as a privileged user, +using the @reqlink{enable} request, by a receiving a privilege bit, or +in an implementation-defined way. @end table @node get-boottime-info @@ -8480,6 +8514,124 @@ There is no conf preceding conf @rarg{start}. +@node get-scheduling +@section get-scheduling [118] (11) Experimental + +@findex get-scheduling +@example + get-scheduling [118] ( session-no : @lt{Session-No} ) + -> ( @lt{Scheduling-Info} ); +@end example + +Get the current scheduling information for a session. You can use 0 +as @rarg{session-no} to get information about the current session. + +@reqlink{set-scheduling} contains an example. + +@subheading Error codes + +The first error code in the list below that is applicable will be +returned. + +@table @errorcode + +@item login-first +Login required before issuing this call, unless @rarg{session-no} is +0 or the number of the current session. + +@item undefined-session +That session does not exist. + +@end table + + +@node set-scheduling +@section set-scheduling [119] (11) Experimental + +@findex set-scheduling +@example + set-scheduling [119] (( session-no : @lt{Session-No}; + priority : @lt{INT16}; + weight : @lt{INT16} )) + -> ( ); +@end example + +This call sets the scheduling priority and weight of the connection. +@ref{Scheduling-Info}, for more information. You can use 0 as +@rarg{session-no} to set the info for the current session. + +@reqexample +@example + 1 118 0 + @t{=1 1 1000} + 2 119 0 0 1000 + @t{%2 58 1} + 3 119 0 1 2500 + @t{%2 59 1500} + 3 119 0 1 1500 + @t{=3} +@end example + +This example uses @reqlink{get-scheduling} to find out the current +scheduling setting (priority 1 and weight 1000). The client then +attempts to get a better priority (0), but is informed that priority 1 +is the best priority available to this user (or before logging in). +At request 3 the client attempts to increase the weight to 2500, but +is informed that 1500 is the best weight available. It finally sets +the weight to 1500. This will result in a 50% speedup compared to the +default setting. + +The @req{set-scheduling} request makes it possible to implement a +quite complex scheduling machinery in the server. Please note, +however, that a server that only implements priority 0 and weight 1 +(and thus treats all sessions equally) is fully compliant with this +specification. The number of priorities and weights that are +available is implementation-defined. They can vary depending on the +privileges of the user that is logged in, and may be affected by the +@reqlink{enable} call. + +@subheading Error codes + +The first error code in the list below that is applicable will be +returned. + +@table @errorcode + +@item weight-zero +You must specify a non-zero @rarg{weight}. + +@item login-first +Login required before issuing this call, unless @rarg{session-no} is +0 or the number of the current session. + +@item undefined-session +That session does not exist. + +@item access-denied +You don't have enough privileges to modify the priority of the +specified session. You can only modify your own session and sessions +logged in as a person you are supervisor of. + +@item index-out-of-range +The @rarg{priority} argument is numerically too large. +@field{error-status} indicates the numerically largest priority that +the server supports. + +@item priority-denied +You don't have enough privileges to lower your priority. +@field{error-status} indicates the lowest priority that you have +access to. + +@item weight-denied +You don't have enough privileges to set the specified weight at the +specified priority. @field{error-status} indicates the highest weight +you have access to at the specified priority. The limit may differ at +different priorities. + +@end table + + + @node Asynchronous Messages @@ -9168,6 +9320,18 @@ A request for a measurement that the server doesn't make has been made. @field{error-status} is undefined. +@item priority-denied (58) +You don't have enough privileges to lower your priority. +@field{error-status} indicates the lowest priority that you have +access to. + +@item weight-denied (59) +You don't have enough privileges to set the specified weight. + +@item weight-zero (60) +The scheduling weight must be non-zero. +@field{error-status} is undefined. + @end table @@ -11187,4 +11351,4 @@ End: @c LocalWords: sven svensson swascii sync synched synching texinfo tkom kent @c LocalWords: ttykom uconf undef unmark userid username val varg yoruba dont @c LocalWords: Nyheter davby Testconf com Unicode roadmap interoperability -@c LocalWords: Bugzilla stats spam SpamAssassin DNS +@c LocalWords: Bugzilla stats spam SpamAssassin DNS boottime