NAME

lonsql - LON TCP-MySQL-Server Daemon for handling database requests.


SYNOPSIS

This script should be run as user=www. Note that a lonsql.pid file contains the pid of the parent process.


OVERVIEW

Purpose within LON-CAPA

LON-CAPA is meant to distribute A LOT of educational content to A LOT of people. It is ineffective to directly rely on contents within the ext2 filesystem to be speedily scanned for on-the-fly searches of content descriptions. (Simply put, it takes a cumbersome amount of time to open, read, analyze, and close thousands of files.)

The solution is to index various data fields that are descriptive of the educational resources on a LON-CAPA server machine in a database. Descriptive data fields are referred to as ``metadata''. The question then arises as to how this metadata is handled in terms of the rest of the LON-CAPA network without burdening client and daemon processes.

The obvious solution, using lonc to send a query to a lond process, doesn't work so well in general as you can see in the following example:

    lonc= loncapa client process    A-lonc= a lonc process on Server A
    lond= loncapa daemon process
                 database command
    A-lonc  --------TCP/IP----------------> B-lond

The problem emerges that A-lonc and B-lond are kept waiting for the MySQL server to ``do its stuff'', or in other words, perform the conceivably sophisticated, data-intensive, time-sucking database transaction. By tying up a lonc and lond process, this significantly cripples the capabilities of LON-CAPA servers.

The solution is to offload the work onto another process, and use lonc and lond just for requests and notifications of completed processing:

                database command
  A-lonc  ---------TCP/IP-----------------> B-lond =====> B-lonsql
         <---------------------------------/                |
           "ok, I'll get back to you..."                    |
                                                            |
                                                            /
  A-lond  <-------------------------------  B-lonc   <======
           "Guess what? I have the result!"

Of course, depending on success or failure, the messages may vary, but the principle remains the same where a separate pool of children processes (lonsql's) handle the MySQL database manipulations.

Thus, lonc and lond spend effectively no time waiting on results from the database.


Internals

Global Variables
dbh
Variables required for forking
$MAX_CLIENTS_PER_CHILD

The number of clients each child should process.

%children

The keys to %children are the current child process IDs

$children

The current number of children

Main body of code.
Read data from loncapa_apache.conf and loncapa.conf.
Ensure we can access the database.
Determine if there are other instances of lonsql running.
Read the hosts file.
Create a socket for lonsql.
Fork once and dissociate from parent.
Write PID to disk.
Prefork children and maintain the population of children.
&make_new_child

Inputs: None

Returns: None

&do_sql_query

Runs an sql metadata table query.

Inputs: $query, $custom, $customshow

Returns: A string containing escaped results.

&logthis

Inputs: $message, the message to log

Returns: nothing

Writes $message to the logfile.

&ishome

Determine if the current machine is the home server for a user. The determination is made by checking the filesystem for the users information.

Inputs: $author

Returns: 0 - this is not the authors home server, 1 - this is.

&courselog

Inputs: $path, $command

Returns: unescaped string of values.

&userlog

Inputs: $path, $command

Returns: unescaped string of values.

Functions required for forking
REAPER

REAPER takes care of dead children.

HUNTSMAN

Signal handler for SIGINT.

HUPSMAN

Signal handler for SIGHUP

DISCONNECT

Disconnects from database.