Common Lisp Package: LFARM-CLIENT.KERNEL

Encompasses the scheduling and execution of remote tasks by connecting to a set of servers.

README:

FUNCTION

Public

BROADCAST-TASK* (TASK &REST ARGS)

Function version of `broadcast-task'. `task' must be a symbol or a lambda form.

CANCEL-TIMEOUT (TIMEOUT TIMEOUT-RESULT)

Attempt to cancel a timeout. If successful, the channel passed to `submit-timeout' will receive `timeout-result'. At most one call to `cancel-timeout' will succeed; others will be ignored. If the timeout has expired on its own then `cancel-timeout' will have no effect. `cancel-timeout' is not available in ABCL.

CHECK-KERNEL

Ensures the value of `*kernel*' is a kernel instance. Provides the MAKE-KERNEL and STORE-VALUE restarts. Returns `*kernel*'.

END-KERNEL (&KEY WAIT)

Disconnect this client. If `wait' is true then wait for servers to end.

KERNEL-NAME

Return the name passed to `make-kernel'.

KERNEL-WORKER-COUNT

Return the number of servers to which in the current kernel is connected.

KILL-TASKS (TASK-CATEGORY &KEY DRY-RUN)

Every task has an associated task category. When a task is submitted, it is assigned the category of `*task-category*' which has a default value of `:default'. `kill-tasks' interrupts running tasks whose category is `eql' to `task-category'. Pending tasks are not affected. If you don't know what to pass for `task-category' then you should probably pass `:default', though this may kill more tasks than you wish. Binding `*task-category*' around `submit-task' enables targeted task killing. If `dry-run' is nil, the function returns the number of tasks killed. If `dry-run' is non-nil then no tasks are killed. In this case the return value is the number of tasks that would have been killed if `dry-run' were nil. `kill-tasks' is not available in ABCL.

MAKE-CHANNEL (&REST ARGS)

Create a channel for submitting and receiving tasks. The current value of `*kernel*' is stored for use in `submit-task'.

MAKE-KERNEL (ADDRESSES &KEY (NAME lfarm-client) ((AUTH *AUTH*) *AUTH*))

Connect to a set of existing servers. `addresses' is a list of (host port) string-integer pairs. `name' is a string for identifying the connection threads.

RECEIVE-RESULT (CHANNEL)

Remove a result from `channel'. If nothing is available the call will block until a result is received.

SUBMIT-TASK* (CHANNEL TASK &REST ARGS)

Function version of `submit-task'. `task' must be a symbol or a lambda form.

SUBMIT-TIMEOUT (CHANNEL TIMEOUT-SECONDS TIMEOUT-RESULT)

Effectively equivalent to (submit-task channel (lambda () (sleep timeout-seconds) timeout-result)) The difference is that `submit-timeout' does not occupy a remote server. A timeout object is returned, which may be passed to `cancel-timeout'.

TASK-CATEGORIES-RUNNING

Return a vector containing the task category currently running for each server.

TRY-RECEIVE-RESULT (CHANNEL)

Non-blocking version of `receive-result'. If a result is available then it is returned as the primary value in (values result t). Otherwise (values nil nil) is returned.

Private

INTERACT (&REST PROMPT)

Read from user and eval.

MAKE-LOCK (&OPTIONAL NAME)

Creates a lock (a mutex) whose name is NAME. If the system does not support multiple threads this will still return some object, but it may not be used for very much.

MAKE-QUEUE (&REST ARGS)

Create a queue. The queue contents may be initialized with the keyword argument `initial-contents'. By default there is no limit on the queue capacity. Passing a `fixed-capacity' keyword argument limits the capacity to the value passed. `push-queue' will block for a full fixed-capacity queue.

POP-QUEUE (QUEUE)

Remove the frontmost element from `queue' and return it. If `queue' is empty, block until an element is available.

PUSH-QUEUE (OBJECT QUEUE)

Push `object' onto the back of `queue'.

SERIALIZE-LAMBDA (LAMBDA-LIST BODY ENV &KEY NAME)

If no closure is detected, return a lambda form. If a closure is detected, generate code for a closure in which the values of the closed-over variables are assigned their current values. When evaluated, the generated code produces a closure equivalent (for our purposes) to a regular lambda with the given `lambda-list' and `body'. The difference is that it holds a snapshot of the closed-over variables rather than the original variables themselves.

Undocumented

%FIND-FREE-SYMBOLS (LAMBDA-LIST BODY)

%MAKE-CHANNEL (&KEY FIXED-CAPACITY)

BROADCAST-KILL (ADDRESSES TASK-CATEGORY-ID)

CALL-WITH-AUTH-ERROR-HANDLER (BODY-FN128)

CALL-WITH-CONNECTION (BODY-FN161)

CALL-WITH-INTERNAL-KERNEL (BODY-FN267 KERNEL)

CALL-WITH-KILL-MONITOR (BODY-FN464)

CALL-WITH-KILL-TRANSLATOR (BODY-FN556)

CALL-WITH-RECONNECT-HANDLER (BODY-FN104)

CLOSURE-LAMBDA-FORM (FORM)

CREATION-ERROR-TRANSLATOR (ERR)

END-CONNECTION (CONNECTION)

ENSURE-LAMBDA-FORM (FORM)

FIND-CAPTURES (LAMBDA-LIST BODY ENV)

FIND-FREE-SYMBOLS (LAMBDA-LIST BODY ENV &OPTIONAL (KNOWN-SYMBOL-MACROS NIL))

FIND-SYMBOL-MACROS (SYMS ENV)

INTERNAL-BROADCAST-TASK (TASK-CATEGORY-ID TASK ARGS FROM-WORKERS TO-WORKERS)

INTERNAL-RECEIVE (CHANNEL)

INTERNAL-TASK (TASK-CATEGORY-ID TASK ARGS HOOK)

INTERNAL-TRY-RECEIVE (CHANNEL)

LAMBDA-FORM (NAME LAMBDA-LIST BODY)

LAMBDA-FORM-P (FORM)

LEXICAL-VAR-P (VAR ENV)

MAKE-BINDINGS (ADDRESSES-QUEUE)

MAKE-CLOSURE-FORM (NAME LAMBDA-LIST BODY ENV LEXICALS SYMBOL-MACROS)

MAKE-CONNECTION (HOST PORT)

MAKE-INTERNAL-KERNEL (&REST ARGS)

MAKE-QUEUE/FILL (LIST)

MAYBE-CONVERT-SYMBOL (FORM)

MAYBE-CONVERT-TASK (FORM)

MAYBE-CONVERT-TASK-FORM (FORM ENV)

MAYBE-MAKE-CLOSURE-FORM (NAME LAMBDA-LIST BODY ENV)

MAYBE-QUOTE-LAMBDA (FORM)

MAYBE-SERIALIZE-LAMBDA (FORM ENV)

MAYBE-STRIP-SHARP-QUOTE (FORM)

NAMED-LAMBDA-FORM (NAME LAMBDA-LIST BODY)

RANDOM-FIXNUM

RECEIVE-BROADCAST-RESULTS (CHANNEL WORKER-COUNT)

RECEIVE-RESULT-FROM-SERVER

REGULAR-LAMBDA-FORM (LAMBDA-LIST BODY)

SEND-KILL (HOST PORT TASK-CATEGORY-ID)

SIMPLE-STYLE-WARNING (MESSAGE &REST ARGS)

SORT-SYMBOLS (SYMBOLS)

STRIP-SHARP-QUOTE (FORM)

SUBMIT-BROADCAST-TASKS (CHANNEL TASK ARGS WORKER-COUNT)

SUBMIT-INTERNAL-TASK (CHANNEL TASK &REST ARGS)

SUBMIT-TASK-TO-SERVER (TASK-CATEGORY-ID TASK &REST ARGS)

SYMBOL-MACRO-P (VAR ENV)

TASK-CATEGORY-ID (TASK-CATEGORY KERNEL)

UNWRAP-RESULT (RESULT)

VARIABLE-INFORMATION (VAR ENV)

WARN* (&REST ARGS)

WORKER-CONTEXT (WORKER-LOOP)

MACRO

Public

BROADCAST-TASK (TASK &REST ARGS &ENVIRONMENT ENV)

Same as `submit-task' except the task is executed on every server. A possible use for this might be to load common code onto servers.

DEFTASK (NAME LAMBDA-LIST &BODY BODY)

Same as `defun' except the function definition is recorded so that it may be submitted as a remote task.

DEFTASK* (NAME LAMBDA-LIST &BODY BODY &ENVIRONMENT ENV)

Same as `deftask' except the function is not compiled locally.

DO-FAST-RECEIVES ((RESULT CHANNEL COUNT) &BODY BODY)

Receive `count' number of results from `channel', executing `body' each time with the result bound to `result'.

SUBMIT-TASK (CHANNEL TASK &REST ARGS &ENVIRONMENT ENV)

Submit a task and its arguments through `channel'. `task' must be a lambda form, a function defined by `deftask', or a function that exists on the servers. `submit-task' translates the syntax of `task' as follows: #'f -> 'f (lambda ..) -> '(lambda ...) with the result being passed to `submit-task*'. This provides the semblance of function syntax when referring to remotely executed code.

Private

WITH-LOCK-HELD ((PLACE) &BODY BODY)

Evaluates BODY with the lock named by PLACE, the value of which is a lock created by MAKE-LOCK. Before the forms in BODY are evaluated, the lock is acquired as if by using ACQUIRE-LOCK. After the forms in BODY have been evaluated, or if a non-local control transfer is caused (e.g. by THROW or SIGNAL), the lock is released as if by RELEASE-LOCK. Note that if the debugger is entered, it is unspecified whether the lock is released at debugger entry or at debugger exit when execution is restarted.

Undocumented

UNWIND-PROTECT/KILL (&KEY MAIN KILL)

WITH-AUTH-ERROR-HANDLER (&BODY BODY154)

WITH-CONNECTION (&BODY BODY202)

WITH-INTERNAL-KERNEL (&WHOLE WHOLE279 (KERNEL) &BODY BODY280)

WITH-KILL-MONITOR (&BODY BODY511)

WITH-KILL-TRANSLATOR (&BODY BODY571)

WITH-RECONNECT-HANDLER (&BODY BODY121)

GENERIC-FUNCTION

Private

Undocumented

INVALID-TASK-ERROR-TASK (CONDITION)

TASK-EXECUTION-ERROR-DESC (CONDITION)

TASK-EXECUTION-ERROR-REPORT (CONDITION)

SLOT-ACCESSOR

Public

Undocumented

KERNEL (OBJECT)

Private

Undocumented

ADDRESSES (OBJECT)

ID (OBJECT)

INTERNAL-CHANNEL (OBJECT)

INTERNAL-KERNEL (OBJECT)

VARIABLE

Public

*DEBUG-TASKS-P*

A do-nothing placeholder for pseudo-compatibility with lparallel.

*KERNEL*

The current kernel, or nil.

*KERNEL-SPIN-COUNT*

A do-nothing placeholder for pseudo-compatibility with lparallel.

*TASK-CATEGORY*

See `kill-tasks'. Default value is `:default'.

*TASK-PRIORITY*

When bound to `:low', the kernel schedules submitted tasks at low priority. Default value is `:default'.

Private

Undocumented

*ERROR-OUTPUT-LOCK*

CLASS

Public

Undocumented

CHANNEL

KERNEL (OBJECT)

CONDITION

Public

INVALID-TASK-ERROR

Error signaled when a non-symbol or non-lambda task is submitted

KERNEL-CREATION-ERROR

Error signaled when `make-kernel' fails.

NO-KERNEL-ERROR

Error signaled when `*kernel*' is nil.

TASK-EXECUTION-ERROR

Error signaled when a task failed to execute on a remote server.

TASK-KILLED-ERROR

Error signaled when attempting to obtain the result of a killed task.

Private

Undocumented

SIMPLE-STYLE-WARNING (MESSAGE &REST ARGS)

TASK-ERROR

CONSTANT

Private

Undocumented

+MAKE-NAMED-LAMBDA-KEY+