external plugin in your favorite programming language. Wow us at how much
easier you can do the same thing in your favorite language. ;-)
+There's now a second external plugin, the [[rst]] plugin, written in
+python. (Could someone convert it into a python library that can be used by
+other plugins?)
+
+[[toc ]]
+
## How external plugins use XML RPC
While XML RPC is typically used over http, ikiwiki doesn't do that.
call `getvar("config", "url")`. To set it, call
`setvar("config", "url", "http://example.com/)`.
+The `%pagestate` is a special hash with a more complex format. To access
+it, external plugins can use the `getstate` and `setstate` RPCs. To access
+stored state, call `getstate("page", "id", "key")`, and to store state,
+call `setstate("page", "id", "key", "value")`.
+
## Notes on function parameters
The [[plugin_interface_documentation|write]] talks about functions that take
"Ikiwiki::rcs_update" and "call" is the RPC call ikiwiki will make whenever
that function is run.
+If the RPC call is memoizable, you can also pass a "memoize" parameter, set
+to 1.
+
## Limitations of XML RPC
Since XML RPC can't pass around references to objects, it can't be used
with functions that take or return such references. That means you can't
-use XML RPC for `cgi` or `formbuilder` hooks (which are passed CGI and
+100% use XML RPC for `cgi` or `formbuilder` hooks (which are passed CGI and
FormBuilder perl objects), or use it to call `template()` (which returns a
perl HTML::Template object).
+Also. the `getopt` hook doesn't work, as ARGV is not available to the external
+plugin.
+
+## Performance issues
+
+Since each external plugin is a separate process, when ikiwiki is
+configured to use lots of external plugins, it will start up slower, and
+use more resources. One or two should not be a problem though.
+
+There is some overhead in using XML RPC for function calls. Most plugins
+should find it to be pretty minimal though. In one benchmark, ikiwiki was
+able to perform 10000 simple XML RPC calls in 11 seconds -- 900 per second.
+
+Using external plugins for hooks such as `sanitize` and `format`, which
+pass around entire pages, and are run for each page rendered, will cause
+more XML RPC overhead than usual, due to the larger number of calls, and the
+large quantity of data conversion going on. In contrast, `preprocess` hooks
+are called generally rarely, and pass around minimal data.
+
+External plugins should avoid making RPC calls unnecessarily (ie, in a loop).
+Memoizing the results of appropriate RPC calls is one good way to minimise the
+number of calls.
+
+Injecting a replacement for a commonly called ikiwiki function
+could result in a lot more RPC calls than expected and slow
+eveything down. `pagetitle`, for instance, is called about 100 times
+per page build. Whenever possible, you should tell ikiwiki to memoize
+injected functions.
+
+In general, use common sense, and your external plugin will probably
+perform ok.