GSoC:2007 Service Clients scm

Erik Massop edited this page Nov 4, 2017 · 1 revision

Overview

Service Client Manager (scm in short) is a meta service client that manages all other local service clients. It will be started automatically when the server starts. And it scans service_clients sub-directory in XMMS2 config dir for service client description files. Each file inside that directory is considered a description file for a single service client, with the name of the file as the name of the service client. This file describes the path of the executable file, arguments passing to that file, if it needs to be launched automatically, service descriptions, versions and method descriptions of a service client. So that clients can query for installed service clients' information even if they are not registered to the server at the moment. Furthermore, clients can control a service client by issuing launch and shutdown requests to scm, or toggle the auto option of the service client. When the server shuts down, scm checks if all local service clients have shut down. If not, it will wait until time out and then kill those which are still running. Otherwise, scm will terminate normally after several seconds.

Remote service clients are not managed by scm. Since they cannot be shut down or launched remotely, and it is impossible to check for the presence of the executable files, it is unnecessary for scm to manage them.

Service client should place a config file with the filename the same as the its own name under service_clients sub-directory in XMMS2 config dir on installation. And on uninstallation, the corresponding config file should be removed as well. scm reads in all config files on startup every time. Besides, scm can also monitor changes made to any config files during runtime. By default, scm will use libinotify kernel feature if you are using a kernel later than 2.6.13. Otherwise, periodic polling method is chosen. Monitoring feature can be enabled/disabled by changing scm configuration. This is discussed in the following section. If you have disabled monitoring feature, but do not want to restart scm in order to read in the changes, you can force scm to check for any changes by issuing a method call to the "poll" method.

Note: Although service client API provides a shutdown feature as well, namely xmmsc_service_shutdown(), it is crucially different from the one provided by scm. For service clients which are managed by scm, you can either try to send a shutdown request by calling xmmsc_service_shutdown() or ask scm to shut it down for you. However, service client has the right to ignore the shutdown request. So xmmsc_service_shutdown() may not always work as expected. In this case, scm will force the service client to shutdown by killing the process if it ignores the shutdown request. To be clear, if you need guaranteed shutdown, use the one provided by scm. This only applies to service clients which are managed by scm!

Configuration

scm is configurable by setting three configvals in the server's config file manually or using configval API. All of the configvals are located in "clients" section and under "scm" client name.

One of them, "monitor", controls whether or not scm should monitor service client config dir using libinotify (if using kernel later than 2.6.13) or by periodic polling (the period is set to 10 seconds by default). The value for this configval can either be "yes" or "no". It is set to "no" by default.

Another configval, "timeout", is the timeout value scm should wait before killing a service client after shutdown request is sent. The value is in milliseconds (1/1000ths of a second). It is set to 10 seconds by default.

The last one, "period", sets the time interval between each polling if periodic polling is used. Like the previous configval, the value is in milliseconds. The default value is also 10 seconds.

Config File Structure

Config file should be placed under service_clients sub-directory in XMMS2 config dir on installation of the service client if it resides on the same machine as the server does. And the name of the config file should be the same as that of the service client. Config file must contain the following information.

  • path to the executable file
  • service name(s)
  • method name(s) and description(s)

The following table shows the keywords and descriptions for each keyword supported by scm.

Keyword Description Type
path path to the executable file string
argv command-line arguments to pass to the executable file string
auto if the service client should be launched automatically "yes" or "no"
[service name] service name should be surrounded by brackets string
description service descriptions string
major major version of service unsigned integer
minor minor version of service unsigned integer

Here is an example of what a config file should look like. Note that "path", "argv" (if any) and "auto" should always come first. Because after "[service name]", every line is considered to be service related information until the next "[service name]".

Contents of file "shutdown"

path=/home/username/xmms2-tutorial/c/service_client/shutdown auto=no [Dummy service] description=This is testing service 1. major=1 minor=0 Dummy method=This is a dummy method.

You may have noticed that I do not have "argv" in the config file, because it is optional and I do not need to pass the executable file any argument. For describing method, method name should show up as the keyword, and method description is on the right hand side of the equal sign.

scm API

There are several services provided by scm, se.xmms.scm.management, se.xmms.scm.query and se.xmms.scm.misc, which deals with service client management, querying service client information and scm-specific configurations, respectively.

Management

se.xmms.scm.management provides the following methods.

Method Name Description
launch Launch a service client
shutdown Shutdown a service client
change_argv Change the command-line argument to pass to a service client
toggle_autostart If a service client should be launched automatically

The following tables list argument and return types of each method described above. Return types are separated by an empty line.

Name Type Description Required
client_name string client name yes
ret uint32 1 for success yes
Name Type Description Required
client_name string client name yes
ret uint32 1 for success yes
Name Type Description Required
client_name string client name yes
argv string command-line arguments to pass to the service client yes
ret uint32 1 for success yes
Name Type Description Required
client_name string client name yes
auto uint32 If the service client should be launched automatically yes
ret uint32 1 for success yes

Querying

se.xmms.scm.query provides the following methods.

Method Name Description
sc_ids List the names of all installed service clients
sc List details of an installed service client
service_ids List the names of all services of a service client
service List details of a service
method_ids List the names of all methods of a service
method List details of a method
lookup_client Search for all service clients which provide the given service

The following tables list argument and return types of each method described above. Return types are separated by an empty line.

Name Type Description Required
ids string list a list of all installed service clients' names no
Name Type Description Required
client_name string client name yes
argv string command-line arguments to pass to the service client yes
auto uint32 If the service client should be launched automatically yes
services uint32 number of services the service client provides yes
Name Type Description Required
client_name string client name yes
ids string list a list of the names of all services the service client provides no
Name Type Description Required
client_name string client name yes
service_name string service name yes
desc string service description yes
major uint32 service major version yes
minor uint32 service minor version yes
registered uint32 if the service is registered on the server yes
methods uint32 number of methods the service provides yes
Name Type Description Required
client_name string client name yes
service_name string service name yes
ids string list a list of the names of all methods the service provides no
Name Type Description Required
client_name string client name yes
service_name string service name yes
method_name string method name yes
desc string method description yes
registered uint32 if the method is registered on the server yes
Name Type Description Required
service_name string service name yes
ids string list a list of the names of all service clients which provide the service no

Miscellaneous

se.xmms.scm.misc provides the following method.

Method Name Description
poll Force the manager to check for any changes in config dir

The "poll" method does not need any arguments and it does not return any values, either.

Go back to Service Client Summary.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.