Commit 3047a07f authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(Session Information): Added Scheduling-Info.

(Protocol Requests): Changed the status of set-keep-commented from
	experimental to recommended.
(get-stats-description): State that this always returns the same
	during a session, so clients can cache this value aggressively.
(get-stats): Elaborate on the access-denied error code.
(get-scheduling): New request.
(set-scheduling): New request.
(Error Codes): Added priority-denied, weight-denied and weight-zero.
parent f2f36681
......@@ -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
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment