/[pcre]/code/trunk/doc/pcre.txt
ViewVC logotype

Diff of /code/trunk/doc/pcre.txt

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 691 by ph10, Sun Sep 11 14:31:21 2011 UTC revision 708 by ph10, Fri Sep 23 11:03:03 2011 UTC
# Line 1888  MATCHING A PATTERN: THE TRADITIONAL FUNC Line 1888  MATCHING A PATTERN: THE TRADITIONAL FUNC
1888         The function pcre_exec() is called to match a subject string against  a         The function pcre_exec() is called to match a subject string against  a
1889         compiled  pattern, which is passed in the code argument. If the pattern         compiled  pattern, which is passed in the code argument. If the pattern
1890         was studied, the result of the study should  be  passed  in  the  extra         was studied, the result of the study should  be  passed  in  the  extra
1891         argument.  This  function is the main matching facility of the library,         argument.  You  can call pcre_exec() with the same code and extra argu-
1892         and it operates in a Perl-like manner. For specialist use there is also         ments as many times as you like, in order to  match  different  subject
1893         an  alternative matching function, which is described below in the sec-         strings with the same pattern.
1894         tion about the pcre_dfa_exec() function.  
1895           This  function  is  the  main  matching facility of the library, and it
1896           operates in a Perl-like manner. For specialist use  there  is  also  an
1897           alternative  matching function, which is described below in the section
1898           about the pcre_dfa_exec() function.
1899    
1900         In most applications, the pattern will have been compiled (and  option-         In most applications, the pattern will have been compiled (and  option-
1901         ally  studied)  in the same process that calls pcre_exec(). However, it         ally  studied)  in the same process that calls pcre_exec(). However, it
# Line 2976  AUTHOR Line 2980  AUTHOR
2980    
2981  REVISION  REVISION
2982    
2983         Last updated: 06 September 2011         Last updated: 23 September 2011
2984         Copyright (c) 1997-2011 University of Cambridge.         Copyright (c) 1997-2011 University of Cambridge.
2985  ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
2986    
# Line 6450  SIMPLE USE OF JIT Line 6454  SIMPLE USE OF JIT
6454         If the JIT compiler finds an unsupported item, no JIT  data  is  gener-         If the JIT compiler finds an unsupported item, no JIT  data  is  gener-
6455         ated.  You  can find out if JIT execution is available after studying a         ated.  You  can find out if JIT execution is available after studying a
6456         pattern by calling pcre_fullinfo() with  the  PCRE_INFO_JIT  option.  A         pattern by calling pcre_fullinfo() with  the  PCRE_INFO_JIT  option.  A
6457         result  of  1 means that JIT compilationw was successful. A result of 0         result  of  1  means that JIT compilation was successful. A result of 0
6458         means that JIT support is not available, or the pattern was not studied         means that JIT support is not available, or the pattern was not studied
6459         with PCRE_STUDY_JIT_COMPILE, or the JIT compiler was not able to handle         with PCRE_STUDY_JIT_COMPILE, or the JIT compiler was not able to handle
6460         the pattern.         the pattern.
6461    
6462           Once a pattern has been studied, with or without JIT, it can be used as
6463           many times as you like for matching different subject strings.
6464    
6465    
6466  UNSUPPORTED OPTIONS AND PATTERN ITEMS  UNSUPPORTED OPTIONS AND PATTERN ITEMS
6467    
6468         The only pcre_exec() options that are supported for JIT  execution  are         The  only  pcre_exec() options that are supported for JIT execution are
6469         PCRE_NO_UTF8_CHECK,   PCRE_NOTBOL,   PCRE_NOTEOL,   PCRE_NOTEMPTY,  and         PCRE_NO_UTF8_CHECK,  PCRE_NOTBOL,   PCRE_NOTEOL,   PCRE_NOTEMPTY,   and
6470         PCRE_NOTEMPTY_ATSTART. Note in particular that partial matching is  not         PCRE_NOTEMPTY_ATSTART.  Note in particular that partial matching is not
6471         supported.         supported.
6472    
6473         The unsupported pattern items are:         The unsupported pattern items are:
# Line 6482  UNSUPPORTED OPTIONS AND PATTERN ITEMS Line 6489  UNSUPPORTED OPTIONS AND PATTERN ITEMS
6489    
6490  RETURN VALUES FROM JIT EXECUTION  RETURN VALUES FROM JIT EXECUTION
6491    
6492         When  a  pattern  is matched using JIT execution, the return values are         When a pattern is matched using JIT execution, the  return  values  are
6493         the same as those given by the interpretive pcre_exec() code, with  the         the  same as those given by the interpretive pcre_exec() code, with the
6494         addition  of  one new error code: PCRE_ERROR_JIT_STACKLIMIT. This means         addition of one new error code: PCRE_ERROR_JIT_STACKLIMIT.  This  means
6495         that the memory used for the JIT stack was insufficient. See  "Control-         that  the memory used for the JIT stack was insufficient. See "Control-
6496         ling the JIT stack" below for a discussion of JIT stack usage. For com-         ling the JIT stack" below for a discussion of JIT stack usage. For com-
6497         patibility with the interpretive pcre_exec() code, no  more  than  two-         patibility  with  the  interpretive pcre_exec() code, no more than two-
6498         thirds  of  the ovector argument is used for passing back captured sub-         thirds of the ovector argument is used for passing back  captured  sub-
6499         strings.         strings.
6500    
6501         The error code PCRE_ERROR_MATCHLIMIT is returned by  the  JIT  code  if         The  error  code  PCRE_ERROR_MATCHLIMIT  is returned by the JIT code if
6502         searching  a  very large pattern tree goes on for too long, as it is in         searching a very large pattern tree goes on for too long, as it  is  in
6503         the same circumstance when JIT is not used, but the details of  exactly         the  same circumstance when JIT is not used, but the details of exactly
6504         what  is  counted are not the same. The PCRE_ERROR_RECURSIONLIMIT error         what is counted are not the same. The  PCRE_ERROR_RECURSIONLIMIT  error
6505         code is never returned by JIT execution.         code is never returned by JIT execution.
6506    
6507    
6508  SAVING AND RESTORING COMPILED PATTERNS  SAVING AND RESTORING COMPILED PATTERNS
6509    
6510         The code that is generated by the  JIT  compiler  is  architecture-spe-         The  code  that  is  generated by the JIT compiler is architecture-spe-
6511         cific,  and  is also position dependent. For those reasons it cannot be         cific, and is also position dependent. For those reasons it  cannot  be
6512         saved and restored like the bytecode and other data of a compiled  pat-         saved  (in a file or database) and restored later like the bytecode and
6513         tern.  You should be able run pcre_study() on a saved and restored pat-         other data of a compiled pattern. Saving and  restoring  compiled  pat-
6514         tern, and thereby recreate the JIT data, but  because  JIT  compilation         terns  is not something many people do. More detail about this facility
6515         uses significant resources, it is probably not worth doing this.         is given in the pcreprecompile documentation. It should be possible  to
6516           run  pcre_study() on a saved and restored pattern, and thereby recreate
6517           the JIT data, but because JIT compilation uses  significant  resources,
6518           it  is  probably  not worth doing this; you might as well recompile the
6519           original pattern.
6520    
6521    
6522  CONTROLLING THE JIT STACK  CONTROLLING THE JIT STACK
6523    
6524         When the compiled JIT code runs, it needs a block of memory to use as a         When the compiled JIT code runs, it needs a block of memory to use as a
6525         stack.  By default, it uses 32K on the  machine  stack.  However,  some         stack.   By  default,  it  uses 32K on the machine stack. However, some
6526         large   or   complicated  patterns  need  more  than  this.  The  error         large  or  complicated  patterns  need  more  than  this.   The   error
6527         PCRE_ERROR_JIT_STACKLIMIT is given when  there  is  not  enough  stack.         PCRE_ERROR_JIT_STACKLIMIT  is  given  when  there  is not enough stack.
6528         Three  functions  are provided for managing blocks of memory for use as         Three functions are provided for managing blocks of memory for  use  as
6529         JIT stacks.         JIT stacks.
6530    
6531         The pcre_jit_stack_alloc() function creates a JIT stack. Its  arguments         The  pcre_jit_stack_alloc() function creates a JIT stack. Its arguments
6532         are  a starting size and a maximum size, and it returns a pointer to an         are a starting size and a maximum size, and it returns a pointer to  an
6533         opaque structure of type pcre_jit_stack, or NULL if there is an  error.         opaque  structure of type pcre_jit_stack, or NULL if there is an error.
6534         The  pcre_jit_stack_free() function can be used to free a stack that is         The pcre_jit_stack_free() function can be used to free a stack that  is
6535         no longer needed. (For the technically minded:  the  address  space  is         no  longer  needed.  (For  the technically minded: the address space is
6536         allocated by mmap or VirtualAlloc.)         allocated by mmap or VirtualAlloc.)
6537    
6538         JIT  uses far less memory for recursion than the interpretive code, and         JIT uses far less memory for recursion than the interpretive code,  and
6539         a maximum stack size of 512K to 1M should be more than enough  for  any         a  maximum  stack size of 512K to 1M should be more than enough for any
6540         pattern.         pattern.
6541    
6542         The  pcre_assign_jit_stack()  function  specifies  which stack JIT code         The pcre_assign_jit_stack() function specifies  which  stack  JIT  code
6543         should use. Its arguments are as follows:         should use. Its arguments are as follows:
6544    
6545           pcre_extra         *extra           pcre_extra         *extra
6546           pcre_jit_callback  callback           pcre_jit_callback  callback
6547           void               *data           void               *data
6548    
6549         The extra argument must be  the  result  of  studying  a  pattern  with         The  extra  argument  must  be  the  result  of studying a pattern with
6550         PCRE_STUDY_JIT_COMPILE.  There  are  three  cases for the values of the         PCRE_STUDY_JIT_COMPILE. There are three cases for  the  values  of  the
6551         other two options:         other two options:
6552    
6553           (1) If callback is NULL and data is NULL, an internal 32K block           (1) If callback is NULL and data is NULL, an internal 32K block
# Line 6551  CONTROLLING THE JIT STACK Line 6562  CONTROLLING THE JIT STACK
6562               is used; otherwise the return value must be a valid JIT stack,               is used; otherwise the return value must be a valid JIT stack,
6563               the result of calling pcre_jit_stack_alloc().               the result of calling pcre_jit_stack_alloc().
6564    
6565         You may safely assign the same JIT stack to more than one  pattern,  as         You  may  safely assign the same JIT stack to more than one pattern, as
6566         long as they are all matched sequentially in the same thread. In a mul-         long as they are all matched sequentially in the same thread. In a mul-
6567         tithread application, each thread must use its own JIT stack.         tithread application, each thread must use its own JIT stack.
6568    
6569         Strictly speaking, even more is allowed. You can assign the same  stack         Strictly  speaking, even more is allowed. You can assign the same stack
6570         to  any number of patterns as long as they are not used for matching by         to any number of patterns as long as they are not used for matching  by
6571         multiple threads at the same time. For example, you can assign the same         multiple threads at the same time. For example, you can assign the same
6572         stack  to all compiled patterns, and use a global mutex in the callback         stack to all compiled patterns, and use a global mutex in the  callback
6573         to wait until the stack is available for use. However, this is an inef-         to wait until the stack is available for use. However, this is an inef-
6574         ficient solution, and not recommended.         ficient solution, and not recommended.
6575    
6576         This  is  a  suggestion  for  how a typical multithreaded program might         This is a suggestion for how  a  typical  multithreaded  program  might
6577         operate:         operate:
6578    
6579           During thread initalization           During thread initalization
# Line 6574  CONTROLLING THE JIT STACK Line 6585  CONTROLLING THE JIT STACK
6585           Use a one-line callback function           Use a one-line callback function
6586             return thread_local_var             return thread_local_var
6587    
6588         All the functions described in this section do nothing if  JIT  is  not         All  the  functions  described in this section do nothing if JIT is not
6589         available,  and  pcre_assign_jit_stack()  does nothing unless the extra         available, and pcre_assign_jit_stack() does nothing  unless  the  extra
6590         argument is non-NULL and points to  a  pcre_extra  block  that  is  the         argument  is  non-NULL  and  points  to  a pcre_extra block that is the
6591         result of a successful study with PCRE_STUDY_JIT_COMPILE.         result of a successful study with PCRE_STUDY_JIT_COMPILE.
6592    
6593    
6594  EXAMPLE CODE  EXAMPLE CODE
6595    
6596         This  is  a  single-threaded example that specifies a JIT stack without         This is a single-threaded example that specifies a  JIT  stack  without
6597         using a callback.         using a callback.
6598    
6599           int rc;           int rc;
# Line 6618  AUTHOR Line 6629  AUTHOR
6629    
6630  REVISION  REVISION
6631    
6632         Last updated: 06 September 2011         Last updated: 23 September 2011
6633         Copyright (c) 1997-2011 University of Cambridge.         Copyright (c) 1997-2011 University of Cambridge.
6634  ------------------------------------------------------------------------------  ------------------------------------------------------------------------------
6635    
Legend:
Removed from v.691  
changed lines
  Added in v.708
  ViewVC Help
Powered by ViewVC 1.1.5